llvm-native-core 0.1.13

//! End-to-end compilation pipeline for the Clang C frontend.
//!
//! Implements the full Clang-style compilation pipeline from source text to
//! object code.  This includes virtual file system management, source location
//! tracking, command-line parsing, and phased compilation (Preprocess → Parse →
//! Sema → CodeGen → Emit).
//!
//! ## Architecture
//!
//! ```text
//! CompilerInvocation  ──►  CompilerInstance
//!   (options)               ├── FileManager (virtual FS, caching)
//!                           ├── SourceManager (file/line/col mapping)
//!                           ├── DiagnosticEngine
//!                           ├── Preprocessor
//!                           ├── ASTContext
//!                           ├── Sema
//!                           └── CodeGen
//!
//! FrontendAction  ──►  CompilationDriver.execute()
//!   (phases)               ├── BeginSourceFile
//!                           ├── Execute
//!                           └── EndSourceFile
//! ```
//!
//! Clean-room behavioral reconstruction from published Clang/LLVM
//! documentation and the Clang driver architecture.

use std::collections::HashMap;
use std::fmt;

use crate::Function;
use crate::Opcode;
use std::fs;
use std::io;
use std::path::{Path, PathBuf};
use std::time::SystemTime;

use crate::module::Module;

use super::ast::*;
use super::codegen::ClangCodeGen;
use super::diagnostics::{
    ClangSourceManager, DiagID, DiagSeverity, DiagnosticBuilder, DiagnosticConsumer,
    DiagnosticEngine, DiagnosticOptions, SourceRange, StructuredDiagnostic,
};
use super::lexer;
use super::parser;
use super::preprocessor::Preprocessor;
use super::sema::Sema;
use super::{CLangStandard, ClangOptions};

// ═══════════════════════════════════════════════════════════════════════════════
// CompilerOptions — comprehensive compile-time settings
// ═══════════════════════════════════════════════════════════════════════════════

/// Detailed compiler options parsed from command-line flags or API calls.
/// This is a richer version of the simpler `ClangOptions` struct, supporting
/// all phases of the compilation pipeline.
#[derive(Debug, Clone)]
pub struct CompilerOptions {
    // ── Language ──────────────────────────────────────────────────────────
    /// C language standard.
    pub standard: CLangStandard,
    /// Treat the input as the given language (c, c++, etc.).
    pub lang: InputLanguage,
    /// Enable GNU extensions.
    pub gnu_extensions: bool,
    /// Enable Microsoft extensions.
    pub ms_extensions: bool,
    /// Enable trigraphs (off by default in C17+).
    pub trigraphs: bool,
    /// Enable digraphs.
    pub digraphs: bool,

    // ── Output ────────────────────────────────────────────────────────────
    /// Output file path (stdout if None).
    pub output_file: Option<PathBuf>,
    /// Compilation phase to stop at.
    pub action: FrontendActionKind,
    /// Output format for textual phases.
    pub output_format: OutputFormat,
    /// Target triple.
    pub target_triple: String,
    /// Target CPU.
    pub target_cpu: Option<String>,
    /// Target features.
    pub target_features: Vec<String>,

    // ── Optimization ──────────────────────────────────────────────────────
    /// Optimization level: 0 through 3, 's' (size), 'z' (aggressive size).
    pub opt_level: OptLevel,
    /// Enable debug info generation.
    pub debug_info: bool,
    /// Debug info kind.
    pub debug_info_kind: DebugInfoKind,

    // ── Diagnostics ───────────────────────────────────────────────────────
    /// Enable warnings.
    pub warnings: bool,
    /// Enable `-Wall`.
    pub wall: bool,
    /// Enable `-Wextra`.
    pub wextra: bool,
    /// Enable `-Wpedantic`.
    pub pedantic: bool,
    /// Treat warnings as errors.
    pub werror: bool,
    /// Disable specific warnings.
    pub wno: Vec<String>,
    /// Enable specific warnings.
    pub w: Vec<String>,
    /// Enable all warnings.
    pub weverything: bool,

    // ── Preprocessor ──────────────────────────────────────────────────────
    /// Include search paths.
    pub includes: Vec<PathBuf>,
    /// System include search paths.
    pub system_includes: Vec<PathBuf>,
    /// Predefined macros (`name`, optional `value`).
    pub defines: Vec<(String, Option<String>)>,
    /// Undefine macros.
    pub undefines: Vec<String>,
    /// Do not search standard system include directories.
    pub nostdinc: bool,
    /// Do not predefine standard macros.
    pub nostdincpp: bool,

    // ── Code Generation ───────────────────────────────────────────────────
    /// Position-independent code.
    pub pic: bool,
    /// Position-independent executable.
    pub pie: bool,
    /// Stack protector level.
    pub stack_protector: i32,
    /// Generate code for coverage.
    pub coverage: bool,
    /// Generate code for profiling.
    pub profile: bool,
    /// Sanitizer flags.
    pub sanitize: Vec<String>,
    /// Thread-local storage model.
    pub tls_model: String,
    /// Emit LLVM IR instead of native code.
    pub emit_llvm: bool,
    /// Emit LLVM bitcode.
    pub emit_bc: bool,
    /// Assembly output file (separate from `output_file` for -S -o).
    pub asm_output: Option<PathBuf>,
    /// Object output file.
    pub obj_output: Option<PathBuf>,
    /// Module output file (IR export).
    pub module_output: Option<PathBuf>,
    /// Only run preprocessor.
    pub preprocess_only: bool,
    /// Only parse (no codegen) — `-fsyntax-only`.
    pub syntax_only: bool,

    // ── Linker ────────────────────────────────────────────────────────────
    /// Linker arguments.
    pub linker_args: Vec<String>,
    /// Static linking.
    pub static_linking: bool,
    /// Shared library output.
    pub shared: bool,
    /// Nodes (multiple input files).
    pub input_files: Vec<PathBuf>,

    // ── Miscellaneous ─────────────────────────────────────────────────────
    /// Verbose output.
    pub verbose: bool,
    /// Show commands but don't execute them.
    pub dry_run: bool,
    /// Print the resource directory and exit.
    pub print_resource_dir: bool,
    /// Print search paths and exit.
    pub print_search_dirs: bool,
    /// Print the target triple and exit.
    pub print_target_triple: bool,
    /// Print version and exit.
    pub print_version: bool,
    /// Print help and exit.
    pub print_help: bool,
    /// Working directory.
    pub working_dir: Option<PathBuf>,
    /// Print compilation statistics.
    pub stats: bool,
}

impl Default for CompilerOptions {
    fn default() -> Self {
        Self {
            standard: CLangStandard::C17,
            lang: InputLanguage::C,
            gnu_extensions: false,
            ms_extensions: false,
            trigraphs: false,
            digraphs: true,
            output_file: None,
            action: FrontendActionKind::EmitObj,
            output_format: OutputFormat::Object,
            target_triple: "x86_64-unknown-linux-gnu".into(),
            target_cpu: None,
            target_features: Vec::new(),
            opt_level: OptLevel::O0,
            debug_info: false,
            debug_info_kind: DebugInfoKind::None,
            warnings: true,
            wall: false,
            wextra: false,
            pedantic: false,
            werror: false,
            wno: Vec::new(),
            w: Vec::new(),
            weverything: false,
            includes: Vec::new(),
            system_includes: Vec::new(),
            defines: Vec::new(),
            undefines: Vec::new(),
            nostdinc: false,
            nostdincpp: false,
            pic: false,
            pie: false,
            stack_protector: 0,
            coverage: false,
            profile: false,
            sanitize: Vec::new(),
            tls_model: "global-dynamic".into(),
            emit_llvm: false,
            emit_bc: false,
            asm_output: None,
            obj_output: None,
            module_output: None,
            preprocess_only: false,
            syntax_only: false,
            linker_args: Vec::new(),
            static_linking: false,
            shared: false,
            input_files: Vec::new(),
            verbose: false,
            dry_run: false,
            print_resource_dir: false,
            print_search_dirs: false,
            print_target_triple: false,
            print_version: false,
            print_help: false,
            working_dir: None,
            stats: false,
        }
    }
}

impl CompilerOptions {
    /// Create from the simpler `ClangOptions`.
    pub fn from_clang_options(opts: &ClangOptions) -> Self {
        Self {
            standard: opts.standard,
            output_file: opts.output_file.as_ref().map(PathBuf::from),
            target_triple: opts.target_triple.clone(),
            opt_level: if opts.optimize {
                OptLevel::O2
            } else {
                OptLevel::O0
            },
            debug_info: opts.debug_info,
            warnings: opts.warnings,
            wall: opts.wall,
            pedantic: opts.pedantic,
            werror: opts.werror,
            includes: opts.includes.iter().map(PathBuf::from).collect(),
            defines: opts.defines.clone(),
            action: FrontendActionKind::EmitObj,
            ..Default::default()
        }
    }
}

// ── Input language ────────────────────────────────────────────────────────────

/// Language of the input source.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum InputLanguage {
    C,
    CXX,
    ObjC,
    ObjCXX,
    OpenCL,
    CUDA,
    Asm,
    LLVM_IR,
}

impl InputLanguage {
    pub fn from_str(s: &str) -> Option<Self> {
        match s {
            "c" => Some(Self::C),
            "c++" | "cxx" => Some(Self::CXX),
            "objective-c" | "objc" => Some(Self::ObjC),
            "objective-c++" | "objc++" => Some(Self::ObjCXX),
            "opencl" | "cl" => Some(Self::OpenCL),
            "cuda" => Some(Self::CUDA),
            "assembler" | "assembler-with-cpp" => Some(Self::Asm),
            "ir" | "llvm-ir" => Some(Self::LLVM_IR),
            _ => None,
        }
    }

    pub fn as_str(&self) -> &'static str {
        match self {
            Self::C => "c",
            Self::CXX => "c++",
            Self::ObjC => "objective-c",
            Self::ObjCXX => "objective-c++",
            Self::OpenCL => "opencl",
            Self::CUDA => "cuda",
            Self::Asm => "assembler",
            Self::LLVM_IR => "ir",
        }
    }
}

impl fmt::Display for InputLanguage {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.as_str())
    }
}

// ── Optimization level ────────────────────────────────────────────────────────

/// Optimization level.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum OptLevel {
    /// No optimization.
    O0,
    /// Moderate optimization.
    O1,
    /// Aggressive optimization.
    O2,
    /// Maximum optimization.
    O3,
    /// Optimize for size.
    Os,
    /// Aggressively optimize for size.
    Oz,
}

impl OptLevel {
    pub fn from_str(s: &str) -> Option<Self> {
        match s {
            "0" => Some(Self::O0),
            "1" => Some(Self::O1),
            "2" => Some(Self::O2),
            "3" => Some(Self::O3),
            "s" => Some(Self::Os),
            "z" => Some(Self::Oz),
            _ => None,
        }
    }

    pub fn to_arg(&self) -> &'static str {
        match self {
            Self::O0 => "-O0",
            Self::O1 => "-O1",
            Self::O2 => "-O2",
            Self::O3 => "-O3",
            Self::Os => "-Os",
            Self::Oz => "-Oz",
        }
    }

    pub fn is_optimizing(&self) -> bool {
        !matches!(self, Self::O0)
    }
}

// ── Debug info kind ───────────────────────────────────────────────────────────

/// Debug info generation kind.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DebugInfoKind {
    /// No debug info.
    None,
    /// Line tables only.
    LineTablesOnly,
    /// Limited debug info.
    Limited,
    /// Full debug info.
    Full,
}

// ── Output format ─────────────────────────────────────────────────────────────

/// Output format for the compilation result.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OutputFormat {
    /// Preprocessed source text.
    PreprocessedSource,
    /// Assembly text.
    Assembly,
    /// Object file.
    Object,
    /// LLVM IR text.
    LLVM_IR,
    /// LLVM bitcode.
    LLVM_BC,
    /// Executable (linked).
    Executable,
    /// Shared library.
    SharedLib,
}

// ── Frontend action kind ──────────────────────────────────────────────────────

/// Which compilation phase (action) to run.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FrontendActionKind {
    /// Preprocess only (`-E`).
    PreprocessOnly,
    /// Parse and type-check only (`-fsyntax-only`).
    SyntaxOnly,
    /// Emit LLVM IR (`.ll`).
    EmitLLVM,
    /// Emit LLVM bitcode (`.bc`).
    EmitBC,
    /// Emit assembly (`.s`).
    EmitAssembly,
    /// Emit object file (`.o`).
    EmitObj,
    /// Full compile + assemble + link.
    EmitExecutable,
    /// Generate PCH.
    GeneratePCH,
    /// Use PCH.
    UsePCH,
    /// Module generation.
    GenerateModule,
    /// Dump AST.
    ASTDump,
    /// Dump tokens.
    DumpTokens,
    /// Dump raw tokens.
    DumpRawTokens,
}

impl FrontendActionKind {
    pub fn from_flag(flag: &str) -> Option<Self> {
        match flag {
            "-E" => Some(Self::PreprocessOnly),
            "-fsyntax-only" => Some(Self::SyntaxOnly),
            "-emit-llvm" => Some(Self::EmitLLVM),
            "-emit-llvm-bc" => Some(Self::EmitBC),
            "-S" => Some(Self::EmitAssembly),
            "-c" => Some(Self::EmitObj),
            "-dump-ast" => Some(Self::ASTDump),
            "-dump-tokens" => Some(Self::DumpTokens),
            "-dump-raw-tokens" => Some(Self::DumpRawTokens),
            _ => None,
        }
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// FileEntry — a file in the virtual file system
// ═══════════════════════════════════════════════════════════════════════════════

/// A cached file entry in the file manager.
///
/// Stores the file's path, contents, size, modification time, and a unique
/// file ID for source location mapping.
#[derive(Debug, Clone)]
pub struct FileEntry {
    /// Unique file identifier.
    pub id: FileID,
    /// Absolute path to the file.
    pub path: PathBuf,
    /// Name used to open the file (may differ from path for virtual files).
    pub name: String,
    /// Cached buffer content, if loaded.
    pub buffer: Option<String>,
    /// Size in bytes.
    pub size: u64,
    /// Modification time, if known.
    pub mod_time: Option<SystemTime>,
    /// Whether this is a virtual/system file.
    pub is_virtual: bool,
    /// Whether the buffer is valid.
    pub is_valid: bool,
    /// Whether this is a system header.
    pub is_system: bool,
    /// Whether this file is from the main source file.
    pub is_main_file: bool,
}

impl FileEntry {
    /// Create a new file entry for a real file.
    pub fn new(id: FileID, path: PathBuf, name: String) -> Self {
        let mut entry = Self {
            id,
            path,
            name,
            buffer: None,
            size: 0,
            mod_time: None,
            is_virtual: false,
            is_valid: true,
            is_system: false,
            is_main_file: false,
        };
        entry.stat();
        entry
    }

    /// Create a virtual file entry (e.g. for built-in sources).
    pub fn virtual_file(id: FileID, name: String, content: String) -> Self {
        let size = content.len() as u64;
        Self {
            id,
            path: PathBuf::from(&name),
            name,
            buffer: Some(content),
            size,
            mod_time: None,
            is_virtual: true,
            is_valid: true,
            is_system: false,
            is_main_file: false,
        }
    }

    /// Stat the file to update size and modification time.
    fn stat(&mut self) {
        if self.is_virtual {
            return;
        }
        if let Ok(meta) = fs::metadata(&self.path) {
            self.size = meta.len();
            self.mod_time = meta.modified().ok();
        } else {
            self.is_valid = false;
        }
    }

    /// Get the file's content as a string, loading from disk if needed.
    pub fn get_buffer(&mut self) -> Result<&str, String> {
        if self.buffer.is_none() {
            if self.is_virtual {
                return Err(format!("virtual file '{}' has no buffer", self.name));
            }
            let content = fs::read_to_string(&self.path)
                .map_err(|e| format!("cannot read file '{}': {}", self.path.display(), e))?;
            self.size = content.len() as u64;
            self.buffer = Some(content);
        }
        Ok(self.buffer.as_ref().unwrap())
    }

    /// Check if the file has been modified since caching.
    pub fn is_stale(&self) -> bool {
        if self.is_virtual {
            return false;
        }
        match fs::metadata(&self.path) {
            Ok(meta) => self.mod_time != meta.modified().ok(),
            Err(_) => true,
        }
    }

    /// Invalidate the cached buffer.
    pub fn invalidate(&mut self) {
        self.buffer = None;
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// FileManager — virtual file system with caching
// ═══════════════════════════════════════════════════════════════════════════════

/// Manages file entries, caching, and virtual file system operations.
///
/// The file manager provides a unified interface for accessing source files,
/// whether they are real files on disk, virtual files (builtins, generated),
/// or memory buffers.
#[derive(Debug)]
pub struct FileManager {
    /// Map from absolute path to file entry.
    cache: HashMap<PathBuf, FileEntry>,
    /// Map from file ID to file entry (for fast lookup by ID).
    files_by_id: HashMap<FileID, PathBuf>,
    /// Next file ID to assign.
    next_file_id: u64,
    /// Include search paths.
    include_paths: Vec<PathBuf>,
    /// System include search paths.
    system_include_paths: Vec<PathBuf>,
    /// Current working directory.
    working_dir: PathBuf,
    /// Overlay virtual file system (filename → contents).
    overlay: HashMap<String, String>,
    /// List of files that are considered system headers.
    system_header_paths: Vec<PathBuf>,
}

impl FileManager {
    /// Create a new file manager.
    pub fn new() -> Self {
        let working_dir = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
        Self {
            cache: HashMap::new(),
            files_by_id: HashMap::new(),
            next_file_id: 1,
            include_paths: Vec::new(),
            system_include_paths: Vec::new(),
            working_dir,
            overlay: HashMap::new(),
            system_header_paths: Vec::new(),
        }
    }

    /// Set the working directory.
    pub fn set_working_dir(&mut self, dir: PathBuf) {
        self.working_dir = dir;
    }

    /// Add an include search path.
    pub fn add_include_path(&mut self, path: PathBuf) {
        self.include_paths.push(path);
    }

    /// Add a system include search path.
    pub fn add_system_include_path(&mut self, path: PathBuf) {
        self.system_include_paths.push(path);
    }

    /// Set the include paths.
    pub fn set_include_paths(&mut self, paths: Vec<PathBuf>) {
        self.include_paths = paths;
    }

    /// Set the system include paths.
    pub fn set_system_include_paths(&mut self, paths: Vec<PathBuf>) {
        self.system_include_paths = paths;
    }

    /// Mark a path as a system header.
    pub fn mark_system_header(&mut self, path: PathBuf) {
        self.system_header_paths.push(path);
    }

    /// Add a virtual file overlay (for testing / builtins).
    pub fn add_overlay(&mut self, filename: String, contents: String) {
        self.overlay.insert(filename, contents);
    }

    /// Get a file entry by path, loading from disk if not in cache.
    pub fn get_file(&mut self, path: &Path) -> Result<FileID, String> {
        // Check overlay first.
        let overlay_contents = self.overlay.get(path.to_str().unwrap_or("")).cloned();
        if let Some(contents) = overlay_contents {
            let fid = self.next_file_id();
            let entry = FileEntry::virtual_file(fid, path.to_string_lossy().to_string(), contents);
            self.cache.insert(path.to_path_buf(), entry);
            self.files_by_id.insert(fid, path.to_path_buf());
            return Ok(fid);
        }

        // Resolve to absolute path.
        let abs = if path.is_absolute() {
            path.to_path_buf()
        } else {
            self.working_dir.join(path)
        };

        // Canonicalize if possible.
        let canonical = fs::canonicalize(&abs).unwrap_or(abs);

        if let Some(entry) = self.cache.get(&canonical) {
            if !entry.is_stale() {
                return Ok(entry.id);
            }
            // Invalidate and re-read.
            self.cache.get_mut(&canonical).unwrap().invalidate();
        }

        let fid = self.next_file_id();
        let name = canonical.to_string_lossy().to_string();
        let mut entry = FileEntry::new(fid, canonical.clone(), name);

        // Check if this is a system header.
        entry.is_system = self.is_system_header(&canonical);

        let _ = entry.get_buffer(); // pre-load
        self.cache.insert(canonical.clone(), entry);
        self.files_by_id.insert(fid, canonical);
        Ok(fid)
    }

    /// Get a virtual file entry by name.
    pub fn get_virtual_file(&mut self, name: &str, content: String) -> Result<FileID, String> {
        let fid = self.next_file_id();
        let entry = FileEntry::virtual_file(fid, name.to_string(), content);
        let path = PathBuf::from(name);
        self.cache.insert(path.clone(), entry);
        self.files_by_id.insert(fid, path);
        Ok(fid)
    }

    /// Get a file entry by file ID.
    pub fn get_file_by_id(&self, fid: FileID) -> Option<&FileEntry> {
        self.files_by_id.get(&fid).and_then(|p| self.cache.get(p))
    }

    /// Get a mutable file entry by file ID.
    pub fn get_file_by_id_mut(&mut self, fid: FileID) -> Option<&mut FileEntry> {
        if let Some(path) = self.files_by_id.get(&fid).cloned() {
            self.cache.get_mut(&path)
        } else {
            None
        }
    }

    /// Get the buffer for a file.
    pub fn get_buffer(&mut self, fid: FileID) -> Result<String, String> {
        let path = self
            .files_by_id
            .get(&fid)
            .cloned()
            .ok_or(format!("unknown file ID {}", fid.0))?;
        let entry = self.cache.get_mut(&path).unwrap();
        let buf = entry.get_buffer()?;
        Ok(buf.to_string())
    }

    /// Look up a file in the include search paths.
    pub fn find_include(&mut self, filename: &str, relative_to: Option<&Path>) -> Option<FileID> {
        // 1. Try relative to the including file.
        if let Some(base) = relative_to {
            if let Some(parent) = base.parent() {
                let candidate = parent.join(filename);
                if let Ok(fid) = self.get_file(&candidate) {
                    return Some(fid);
                }
            }
        }

        // 2. Try current directory.
        let candidate = self.working_dir.join(filename);
        if let Ok(fid) = self.get_file(&candidate) {
            return Some(fid);
        }

        // 3. Try user include paths.
        let user_dirs: Vec<PathBuf> = self.include_paths.iter().cloned().collect();
        for dir in &user_dirs {
            let candidate = dir.join(filename);
            if let Ok(fid) = self.get_file(&candidate) {
                return Some(fid);
            }
        }

        // 4. Try system include paths.
        let system_dirs: Vec<PathBuf> = self.system_include_paths.iter().cloned().collect();
        for dir in &system_dirs {
            let candidate = dir.join(filename);
            if let Ok(fid) = self.get_file(&candidate) {
                return Some(fid);
            }
        }

        None
    }

    /// Check if a path is a system header.
    fn is_system_header(&self, path: &Path) -> bool {
        self.system_header_paths
            .iter()
            .any(|sp| path.starts_with(sp))
    }

    /// Allocate a new file ID.
    fn next_file_id(&mut self) -> FileID {
        let id = FileID(self.next_file_id);
        self.next_file_id += 1;
        id
    }

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

    /// Clear the cache.
    pub fn clear(&mut self) {
        self.cache.clear();
        self.files_by_id.clear();
        self.next_file_id = 1;
    }
}

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

// ═══════════════════════════════════════════════════════════════════════════════
// FileID — unique identifier for a file in the source manager
// ═══════════════════════════════════════════════════════════════════════════════

/// Unique identifier for a file.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct FileID(pub u64);

impl fmt::Display for FileID {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "fid:{}", self.0)
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// SourceLineEntry — one line in the line table
// ═══════════════════════════════════════════════════════════════════════════════

/// A single entry in the source line table.
#[derive(Debug, Clone)]
pub struct SourceLineEntry {
    /// Line number (1-based).
    pub line: u32,
    /// Byte offset into the file buffer where this line starts.
    pub offset: u32,
}

// ═══════════════════════════════════════════════════════════════════════════════
// SourceLocation — precise location in source code
// ═══════════════════════════════════════════════════════════════════════════════

/// A source location: file + offset or macro expansion location.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct SourceLocation {
    /// The file ID (0 = invalid).
    pub file_id: u64,
    /// Byte offset into the file buffer.
    pub offset: u32,
    /// Line number (1-based, cached).
    pub line: u32,
    /// Column number (1-based, cached).
    pub column: u32,
}

impl SourceLocation {
    /// Create an invalid source location.
    pub fn invalid() -> Self {
        Self {
            file_id: 0,
            offset: 0,
            line: 0,
            column: 0,
        }
    }

    /// Check if this location is valid.
    pub fn is_valid(&self) -> bool {
        self.file_id != 0
    }

    /// Check if this location is in the main file.
    pub fn is_in_main_file(&self) -> bool {
        self.file_id == 1
    }

    /// Format as `file:line:column`.
    pub fn to_display(&self, sm: &SourceManager) -> String {
        if !self.is_valid() {
            return "<invalid loc>".to_string();
        }
        let name = sm
            .get_file_by_id(FileID(self.file_id))
            .map(|e| e.name.clone())
            .unwrap_or_else(|| format!("<fid:{}>", self.file_id));
        format!("{}:{}:{}", name, self.line, self.column)
    }
}

impl fmt::Display for SourceLocation {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if self.is_valid() {
            write!(f, "<{}:{}:{}>", self.file_id, self.line, self.column)
        } else {
            write!(f, "<invalid>")
        }
    }
}

impl Default for SourceLocation {
    fn default() -> Self {
        Self::invalid()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// SourceManager — maps source locations to file/line/column
// ═══════════════════════════════════════════════════════════════════════════════

/// Manages source files, mapping file IDs and byte offsets to precise
/// file/line/column locations.  Maintains a line table for each loaded file
/// for rapid offset-to-line translation.
#[derive(Debug)]
pub struct SourceManager {
    /// File manager for file operations.
    file_manager: FileManager,
    /// Main file ID.
    main_file_id: Option<FileID>,
    /// Line tables per file.  Keyed by FileID, value is Vec of (offset, line) pairs.
    line_tables: HashMap<FileID, Vec<SourceLineEntry>>,
    /// Cached buffers per file.
    buffers: HashMap<FileID, String>,
    /// Whether line tables have been built.
    line_tables_built: HashMap<FileID, bool>,
}

impl SourceManager {
    /// Create a new source manager.
    pub fn new(file_manager: FileManager) -> Self {
        Self {
            file_manager,
            main_file_id: None,
            line_tables: HashMap::new(),
            buffers: HashMap::new(),
            line_tables_built: HashMap::new(),
        }
    }

    /// Set the main source file.
    pub fn set_main_file(&mut self, fid: FileID) {
        self.main_file_id = Some(fid);
    }

    /// Get the main file ID.
    pub fn main_file_id(&self) -> Option<FileID> {
        self.main_file_id
    }

    /// Load a source file from disk.
    pub fn load_file(&mut self, path: &Path) -> Result<FileID, String> {
        let fid = self.file_manager.get_file(path)?;
        if self.main_file_id.is_none() {
            self.main_file_id = Some(fid);
        }
        let entry = self.file_manager.get_file_by_id(fid).unwrap();
        let is_main = self.main_file_id == Some(fid);
        let marker = if is_main {
            self.file_manager
                .get_file_by_id_mut(fid)
                .unwrap()
                .is_main_file = true;
        };
        let _ = marker;
        self.ensure_buffer(fid)?;
        self.build_line_table(fid)?;
        Ok(fid)
    }

    /// Load a virtual file.
    pub fn load_virtual_file(&mut self, name: &str, content: String) -> Result<FileID, String> {
        let fid = self.file_manager.get_virtual_file(name, content)?;
        if self.main_file_id.is_none() {
            self.main_file_id = Some(fid);
        }
        self.ensure_buffer(fid)?;
        self.build_line_table(fid)?;
        Ok(fid)
    }

    /// Get the FileManager reference.
    pub fn file_manager(&self) -> &FileManager {
        &self.file_manager
    }

    /// Get the mutable FileManager reference.
    pub fn file_manager_mut(&mut self) -> &mut FileManager {
        &mut self.file_manager
    }

    /// Ensure the buffer for a file is cached.
    fn ensure_buffer(&mut self, fid: FileID) -> Result<(), String> {
        if !self.buffers.contains_key(&fid) {
            let buf = self.file_manager.get_buffer(fid)?;
            self.buffers.insert(fid, buf);
        }
        Ok(())
    }

    /// Build the line table for a file.
    fn build_line_table(&mut self, fid: FileID) -> Result<(), String> {
        if self.line_tables_built.get(&fid) == Some(&true) {
            return Ok(());
        }

        let buffer = self
            .buffers
            .get(&fid)
            .ok_or(format!("no buffer for file {}", fid))?
            .clone();
        let mut lines = Vec::new();
        lines.push(SourceLineEntry { line: 1, offset: 0 });

        let mut offset = 0u32;
        for ch in buffer.chars() {
            if ch == '\n' {
                lines.push(SourceLineEntry {
                    line: lines.len() as u32 + 1,
                    offset: offset + 1,
                });
            }
            offset += ch.len_utf8() as u32;
        }

        self.line_tables.insert(fid, lines);
        self.line_tables_built.insert(fid, true);
        Ok(())
    }

    /// Compute a source location from a file ID and byte offset.
    pub fn get_location(&self, fid: FileID, offset: u32) -> SourceLocation {
        let line_table = match self.line_tables.get(&fid) {
            Some(lt) => lt,
            None => {
                return SourceLocation {
                    file_id: fid.0,
                    offset,
                    line: 0,
                    column: 0,
                };
            }
        };

        // Binary search: find the last entry with offset <= the given offset.
        let idx = match line_table.binary_search_by(|entry| entry.offset.cmp(&offset)) {
            Ok(i) => i,
            Err(i) => i.saturating_sub(1),
        };

        let entry = &line_table[idx];
        let line = entry.line;
        let column = (offset - entry.offset) + 1;

        SourceLocation {
            file_id: fid.0,
            offset,
            line,
            column,
        }
    }

    /// Get the source text for a range of locations.
    pub fn get_source_text(&self, start: SourceLocation, end: SourceLocation) -> String {
        if start.file_id != end.file_id || start.file_id == 0 {
            return String::new();
        }
        let fid = FileID(start.file_id);
        if let Some(buffer) = self.buffers.get(&fid) {
            let s = start.offset as usize;
            let e = end.offset as usize;
            if s <= e && e <= buffer.len() {
                return buffer[s..e].to_string();
            }
        }
        String::new()
    }

    /// Get the line of source text at a location.
    pub fn get_line(&self, loc: SourceLocation) -> Option<String> {
        if loc.file_id == 0 {
            return None;
        }
        let fid = FileID(loc.file_id);
        let buffer = self.buffers.get(&fid)?;
        let line_table = self.line_tables.get(&fid)?;

        let idx = match line_table.binary_search_by(|entry| entry.offset.cmp(&loc.offset)) {
            Ok(i) => i,
            Err(i) => i.saturating_sub(1),
        };

        let line_start = line_table[idx].offset as usize;
        let line_end = if idx + 1 < line_table.len() {
            line_table[idx + 1].offset as usize
        } else {
            buffer.len()
        };

        // Strip trailing newline.
        let mut line = buffer[line_start..line_end].to_string();
        if line.ends_with('\n') {
            line.pop();
        }
        if line.ends_with('\r') {
            line.pop();
        }
        Some(line)
    }

    /// Get the file entry for a file ID.
    pub fn get_file_by_id(&self, fid: FileID) -> Option<&FileEntry> {
        self.file_manager.get_file_by_id(fid)
    }

    /// Get the buffer for a file.
    pub fn get_buffer(&self, fid: FileID) -> Option<&str> {
        self.buffers.get(&fid).map(|s| s.as_str())
    }

    /// Get the number of files managed.
    pub fn num_files(&self) -> usize {
        self.file_manager.num_files()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// ASTConsumer — consumes AST nodes as they are produced
// ═══════════════════════════════════════════════════════════════════════════════

/// Trait for AST consumers — handles top-level declarations as they are parsed.
///
/// In a real Clang, consumers receive declarations as the parser produces them,
/// enabling incremental compilation and IDE features.
pub trait ASTConsumer: fmt::Debug {
    /// Called when translation unit parsing begins.
    fn handle_translation_unit_begin(&mut self, _tu: &TranslationUnit) {}

    /// Handle a top-level declaration.
    fn handle_top_level_decl(&mut self, decl: &Decl);

    /// Called after all declarations have been processed.
    fn handle_translation_unit_end(&mut self, _tu: &TranslationUnit) {}

    /// Called when the consumer is done.
    fn finish(&mut self) {}

    /// Print final statistics.
    fn print_stats(&self) {}
}

// ── Built-in consumer implementations ─────────────────────────────────────────

/// A consumer that does nothing (syntax-only mode).
#[derive(Debug)]
pub struct SyntaxOnlyConsumer;

impl ASTConsumer for SyntaxOnlyConsumer {
    fn handle_top_level_decl(&mut self, _decl: &Decl) {}
}

/// A consumer that dumps the AST to stdout.
#[derive(Debug)]
pub struct ASTDumpConsumer;

impl ASTConsumer for ASTDumpConsumer {
    fn handle_top_level_decl(&mut self, decl: &Decl) {
        println!("{}", decl);
    }
}

/// A consumer that generates LLVM IR.
pub struct CodeGenConsumer<'a> {
    /// The code generator.
    pub codegen: ClangCodeGen<'a>,
}

impl<'a> fmt::Debug for CodeGenConsumer<'a> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CodeGenConsumer")
            .field("codegen", &"<ClangCodeGen>")
            .finish()
    }
}

impl<'a> CodeGenConsumer<'a> {
    pub fn new(codegen: ClangCodeGen<'a>) -> Self {
        Self { codegen }
    }
}

impl ASTConsumer for CodeGenConsumer<'_> {
    fn handle_top_level_decl(&mut self, _decl: &Decl) {
        // Codegen handles compilation at the TU level.
    }

    fn handle_translation_unit_begin(&mut self, _tu: &TranslationUnit) {}

    fn handle_translation_unit_end(&mut self, tu: &TranslationUnit) {
        let _ = self.codegen.compile(tu);
    }
}

/// Multiplexing consumer — dispatches to multiple sub-consumers.
pub struct MultiplexConsumer {
    pub consumers: Vec<Box<dyn ASTConsumer>>,
}

impl fmt::Debug for MultiplexConsumer {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("MultiplexConsumer")
            .field("num_consumers", &self.consumers.len())
            .finish()
    }
}

impl MultiplexConsumer {
    pub fn new(consumers: Vec<Box<dyn ASTConsumer>>) -> Self {
        Self { consumers }
    }

    pub fn add(&mut self, consumer: Box<dyn ASTConsumer>) {
        self.consumers.push(consumer);
    }
}

impl ASTConsumer for MultiplexConsumer {
    fn handle_translation_unit_begin(&mut self, tu: &TranslationUnit) {
        for c in &mut self.consumers {
            c.handle_translation_unit_begin(tu);
        }
    }

    fn handle_top_level_decl(&mut self, decl: &Decl) {
        for c in &mut self.consumers {
            c.handle_top_level_decl(decl);
        }
    }

    fn handle_translation_unit_end(&mut self, tu: &TranslationUnit) {
        for c in &mut self.consumers {
            c.handle_translation_unit_end(tu);
        }
    }

    fn finish(&mut self) {
        for c in &mut self.consumers {
            c.finish();
        }
    }

    fn print_stats(&self) {
        for c in &self.consumers {
            c.print_stats();
        }
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// FrontendAction — base class for all frontend actions
// ═══════════════════════════════════════════════════════════════════════════════

/// A frontend action represents one "unit of work" for the compiler.
/// Subclasses define specific actions like emitting object files, assembly,
/// or LLVM IR.
#[derive(Debug)]
pub enum FrontendAction {
    PreprocessOnly(PreprocessOnlyAction),
    SyntaxOnly(SyntaxOnlyAction),
    EmitLLVM(EmitLLVMAction),
    EmitBC(EmitBCAction),
    EmitAssembly(EmitAssemblyAction),
    EmitObj(EmitObjAction),
    ASTDump(ASTDumpAction),
    DumpTokens(DumpTokensAction),
}

impl FrontendAction {
    /// Create a frontend action for the given kind.
    pub fn for_kind(kind: FrontendActionKind) -> Self {
        match kind {
            FrontendActionKind::PreprocessOnly => {
                Self::PreprocessOnly(PreprocessOnlyAction { output: None })
            }
            FrontendActionKind::SyntaxOnly => Self::SyntaxOnly(SyntaxOnlyAction),
            FrontendActionKind::EmitLLVM => Self::EmitLLVM(EmitLLVMAction { output: None }),
            FrontendActionKind::EmitBC => Self::EmitBC(EmitBCAction),
            FrontendActionKind::EmitAssembly => {
                Self::EmitAssembly(EmitAssemblyAction { output: None })
            }
            FrontendActionKind::EmitObj => Self::EmitObj(EmitObjAction::new()),
            FrontendActionKind::ASTDump => Self::ASTDump(ASTDumpAction),
            FrontendActionKind::DumpTokens => Self::DumpTokens(DumpTokensAction { output: None }),
            // Default to EmitObj for unsupported actions.
            _ => Self::EmitObj(EmitObjAction::new()),
        }
    }

    /// Begin source file processing.
    pub fn begin_source_file(
        &mut self,
        compiler: &mut CompilerInstance,
    ) -> Result<(), Vec<String>> {
        match self {
            Self::PreprocessOnly(action) => action.begin_source_file(compiler),
            Self::SyntaxOnly(action) => action.begin_source_file(compiler),
            Self::EmitLLVM(action) => action.begin_source_file(compiler),
            Self::EmitBC(action) => action.begin_source_file(compiler),
            Self::EmitAssembly(action) => action.begin_source_file(compiler),
            Self::EmitObj(action) => action.begin_source_file(compiler),
            Self::ASTDump(action) => action.begin_source_file(compiler),
            Self::DumpTokens(action) => action.begin_source_file(compiler),
        }
    }

    /// Execute the action.
    pub fn execute(&mut self) -> Result<(), Vec<String>> {
        match self {
            Self::PreprocessOnly(action) => action.execute(),
            Self::SyntaxOnly(action) => action.execute(),
            Self::EmitLLVM(action) => action.execute(),
            Self::EmitBC(action) => action.execute(),
            Self::EmitAssembly(action) => action.execute(),
            Self::EmitObj(action) => action.execute(),
            Self::ASTDump(action) => action.execute(),
            Self::DumpTokens(action) => action.execute(),
        }
    }

    /// End source file processing.
    pub fn end_source_file(&mut self) -> Result<(), Vec<String>> {
        match self {
            Self::PreprocessOnly(action) => action.end_source_file(),
            Self::SyntaxOnly(action) => action.end_source_file(),
            Self::EmitLLVM(action) => action.end_source_file(),
            Self::EmitBC(action) => action.end_source_file(),
            Self::EmitAssembly(action) => action.end_source_file(),
            Self::EmitObj(action) => action.end_source_file(),
            Self::ASTDump(action) => action.end_source_file(),
            Self::DumpTokens(action) => action.end_source_file(),
        }
    }

    /// Get the output buffer for actions that produce text.
    pub fn get_output(&self) -> Option<String> {
        match self {
            Self::PreprocessOnly(action) => action.get_output(),
            Self::EmitLLVM(action) => action.get_output(),
            Self::EmitAssembly(action) => action.get_output(),
            Self::DumpTokens(action) => action.get_output(),
            _ => None,
        }
    }

    /// Get the object bytes for EmitObjAction.
    pub fn get_object_bytes(&self) -> Option<Vec<u8>> {
        match self {
            Self::EmitObj(action) => action.get_object_bytes(),
            _ => None,
        }
    }
}

// ── Action trait ──────────────────────────────────────────────────────────────

/// Internal trait implemented by all concrete actions.
trait ActionImpl {
    fn begin_source_file(&mut self, compiler: &mut CompilerInstance) -> Result<(), Vec<String>>;
    fn execute(&mut self) -> Result<(), Vec<String>>;
    fn end_source_file(&mut self) -> Result<(), Vec<String>>;
    fn get_output(&self) -> Option<String> {
        None
    }
}

// ── PreprocessOnlyAction ──────────────────────────────────────────────────────

/// Action that only runs the preprocessor and outputs the result.
#[derive(Debug)]
pub struct PreprocessOnlyAction {
    output: Option<String>,
}

impl ActionImpl for PreprocessOnlyAction {
    fn begin_source_file(&mut self, _compiler: &mut CompilerInstance) -> Result<(), Vec<String>> {
        self.output = Some(String::new());
        Ok(())
    }

    fn execute(&mut self) -> Result<(), Vec<String>> {
        // Preprocessing is done in the CompilerInstance; here we just pass.
        Ok(())
    }

    fn end_source_file(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn get_output(&self) -> Option<String> {
        self.output.clone()
    }
}

// ── SyntaxOnlyAction ──────────────────────────────────────────────────────────

/// Action that parses and type-checks without generating code.
#[derive(Debug)]
pub struct SyntaxOnlyAction;

impl ActionImpl for SyntaxOnlyAction {
    fn begin_source_file(&mut self, _compiler: &mut CompilerInstance) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn execute(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn end_source_file(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }
}

// ── EmitLLVMAction ────────────────────────────────────────────────────────────

/// Action that emits LLVM IR (`.ll` file).
#[derive(Debug)]
pub struct EmitLLVMAction {
    output: Option<String>,
}

impl ActionImpl for EmitLLVMAction {
    fn begin_source_file(&mut self, _compiler: &mut CompilerInstance) -> Result<(), Vec<String>> {
        self.output = Some(String::new());
        Ok(())
    }

    fn execute(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn end_source_file(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn get_output(&self) -> Option<String> {
        self.output.clone()
    }
}

// ── EmitBCAction ──────────────────────────────────────────────────────────────

/// Action that emits LLVM bitcode (`.bc` file).
#[derive(Debug)]
pub struct EmitBCAction;

impl ActionImpl for EmitBCAction {
    fn begin_source_file(&mut self, _compiler: &mut CompilerInstance) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn execute(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn end_source_file(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }
}

// ── EmitAssemblyAction ────────────────────────────────────────────────────────

/// Action that emits assembly (`.s` file).
#[derive(Debug)]
pub struct EmitAssemblyAction {
    output: Option<String>,
}

impl ActionImpl for EmitAssemblyAction {
    fn begin_source_file(&mut self, _compiler: &mut CompilerInstance) -> Result<(), Vec<String>> {
        self.output = Some(String::new());
        Ok(())
    }

    fn execute(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn end_source_file(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn get_output(&self) -> Option<String> {
        self.output.clone()
    }
}

// ── EmitObjAction ─────────────────────────────────────────────────────────────

/// Action that emits an object file (`.o` file).
#[derive(Debug)]
pub struct EmitObjAction {
    module: Option<Module>,
}

impl EmitObjAction {
    pub fn new() -> Self {
        Self { module: None }
    }

    pub fn set_module(&mut self, module: Module) {
        self.module = Some(module);
    }

    pub fn get_object_bytes(&self) -> Option<Vec<u8>> {
        // In a real implementation, this would use the target machine
        // to emit object code.  Here we return an empty vector.
        Some(Vec::new())
    }
}

impl ActionImpl for EmitObjAction {
    fn begin_source_file(&mut self, _compiler: &mut CompilerInstance) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn execute(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn end_source_file(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }
}

// ── ASTDumpAction ─────────────────────────────────────────────────────────────

/// Action that dumps the AST to stdout.
#[derive(Debug)]
pub struct ASTDumpAction;

impl ActionImpl for ASTDumpAction {
    fn begin_source_file(&mut self, _compiler: &mut CompilerInstance) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn execute(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn end_source_file(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }
}

// ── DumpTokensAction ──────────────────────────────────────────────────────────

/// Action that dumps tokens to stdout.
#[derive(Debug)]
pub struct DumpTokensAction {
    output: Option<String>,
}

impl ActionImpl for DumpTokensAction {
    fn begin_source_file(&mut self, _compiler: &mut CompilerInstance) -> Result<(), Vec<String>> {
        self.output = Some(String::new());
        Ok(())
    }

    fn execute(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn end_source_file(&mut self) -> Result<(), Vec<String>> {
        Ok(())
    }

    fn get_output(&self) -> Option<String> {
        self.output.clone()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// CompilerInstance — owns all compilation state
// ═══════════════════════════════════════════════════════════════════════════════

/// The central compilation object, analogous to `clang::CompilerInstance`.
///
/// Owns all compilation state including diagnostics, the target, source
/// manager, file manager, preprocessor, AST context, semantic analyzer,
/// and code generator, all configured via a `CompilerInvocation`.
#[derive(Debug)]
pub struct CompilerInstance {
    /// Compiler options.
    pub opts: CompilerOptions,
    /// Diagnostic engine.
    pub diagnostics: DiagnosticEngine,
    /// Source manager.
    pub source_manager: SourceManager,
    /// Whether source file processing has begun.
    source_file_begun: bool,
    /// Whether we have an AST.
    has_ast: bool,
    /// The parsed translation unit.
    translation_unit: Option<TranslationUnit>,
    /// Output stream for textual output.
    output_buffer: Option<String>,
}

impl CompilerInstance {
    /// Create a new compiler instance from a compiler invocation.
    pub fn new(invocation: CompilerInvocation) -> Self {
        let mut diag_engine = DiagnosticEngine::new(ClangSourceManager::new());
        diag_engine.set_warnings_as_errors(invocation.opts.werror);
        if !invocation.opts.warnings {
            diag_engine.set_ignore_warnings(true);
        }

        let mut fm = FileManager::new();
        fm.set_include_paths(invocation.opts.includes.clone());
        fm.set_system_include_paths(invocation.opts.system_includes.clone());

        Self {
            opts: invocation.opts,
            diagnostics: diag_engine,
            source_manager: SourceManager::new(fm),
            source_file_begun: false,
            has_ast: false,
            translation_unit: None,
            output_buffer: None,
        }
    }

    /// Create a compiler instance with default options.
    pub fn create_default() -> Self {
        Self::new(CompilerInvocation::default())
    }

    /// Get the compiler options.
    pub fn options(&self) -> &CompilerOptions {
        &self.opts
    }

    /// Get mutable compiler options.
    pub fn options_mut(&mut self) -> &mut CompilerOptions {
        &mut self.opts
    }

    /// Get the target triple.
    pub fn target_triple(&self) -> &str {
        &self.opts.target_triple
    }

    // ── Source file management ─────────────────────────────────────────

    /// Begin processing a source file.
    pub fn begin_source_file(&mut self, action: &mut FrontendAction) -> Result<(), Vec<String>> {
        if self.source_file_begun {
            return Err(vec!["source file already begun".to_string()]);
        }
        self.source_file_begun = true;
        action.begin_source_file(self)?;

        // Run lexer, preprocessor, parser, and sema.
        if self.opts.preprocess_only {
            self.output_buffer = Some(self.run_preprocessor_only()?);
        } else {
            self.translation_unit = Some(self.run_parse_and_sema()?);
            self.has_ast = true;
        }

        Ok(())
    }

    /// End processing the source file.
    pub fn end_source_file(&mut self) -> Result<(), Vec<String>> {
        if !self.source_file_begun {
            return Ok(());
        }
        self.source_file_begun = false;
        Ok(())
    }

    /// Run the full compilation pipeline for source in a virtual file.
    pub fn run_pipeline(
        &mut self,
        virtual_name: &str,
        source: &str,
    ) -> Result<Module, Vec<String>> {
        // Load the source into a virtual file.
        let _fid = self
            .source_manager
            .load_virtual_file(virtual_name, source.to_string())
            .map_err(|e| vec![e])?;

        // Run lexer on the source.
        let tokens = lexer::tokenize(source, self.opts.standard);

        // Run preprocessor.
        let _pp = Preprocessor::new(self.opts.standard);
        // (Preprocessing is handled via the Preprocessor; here we note
        //  that the lexer already tokenized.)

        // If preprocessing only, return.
        if self.opts.preprocess_only {
            return Err(vec!["preprocessing only; no module produced".to_string()]);
        }

        // Parse.
        let mut p = parser::Parser::new(&tokens, self.opts.standard);
        let tu = p.parse().map_err(|e| {
            e.into_iter()
                .map(|err| format!("parse error: {}", err))
                .collect::<Vec<_>>()
        })?;

        // Semantic analysis.
        let mut sema = Sema::new(self.opts.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());
        }

        // Syntax-only mode.
        if self.opts.syntax_only {
            return Err(vec!["syntax-only; no module produced".to_string()]);
        }

        // Code generation.
        let mut cg = ClangCodeGen::new("input", &self.opts.target_triple);
        cg.compile(&tu).map_err(|e| {
            e.iter()
                .map(|err| format!("codegen error: {}", err))
                .collect::<Vec<_>>()
        })?;

        // Return the module (ClangCodeGen owns the module; we move it).
        let module = cg.module;
        Ok(module)
    }

    // ── Internal helpers ───────────────────────────────────────────────

    /// Run only the preprocessor and return the preprocessed text.
    fn run_preprocessor_only(&mut self) -> Result<String, Vec<String>> {
        let fid = self
            .source_manager
            .main_file_id()
            .ok_or_else(|| vec!["no main file for preprocessing".to_string()])?;

        let source = self
            .source_manager
            .get_buffer(fid)
            .map(|s| s.to_string())
            .ok_or_else(|| vec!["no buffer for main file".to_string()])?;

        // Run the preprocessor on the source.
        let _pp = Preprocessor::new(self.opts.standard);

        // In a real implementation, we'd collect the preprocessor output.
        // For now, we return the original source (placeholder).
        Ok(source)
    }

    /// Run lexer, parser, and semantic analysis.
    fn run_parse_and_sema(&mut self) -> Result<TranslationUnit, Vec<String>> {
        let fid = self
            .source_manager
            .main_file_id()
            .ok_or_else(|| vec!["no main file for parsing".to_string()])?;

        let source = self
            .source_manager
            .get_buffer(fid)
            .map(|s| s.to_string())
            .ok_or_else(|| vec!["no buffer for main file".to_string()])?;

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

        let mut sema = Sema::new(self.opts.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());
        }

        Ok(tu)
    }

    /// Execute code generation on the parsed AST.
    pub fn execute_codegen(&mut self) -> Result<(), Vec<String>> {
        let standard = self.opts.standard;
        let triple = self.opts.target_triple.clone();

        let fid = self
            .source_manager
            .main_file_id()
            .ok_or_else(|| vec!["no main file for codegen".to_string()])?;
        let source = self
            .source_manager
            .get_buffer(fid)
            .ok_or_else(|| vec!["no buffer for main file".to_string()])?;

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

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

        let mut cg = ClangCodeGen::new("input", &triple);
        cg.compile(&tu).map_err(|e| {
            e.iter()
                .map(|e| format!("codegen error: {}", e))
                .collect::<Vec<_>>()
        })?;

        Ok(())
    }

    /// Get the parsed translation unit.
    pub fn get_translation_unit(&self) -> Option<&TranslationUnit> {
        self.translation_unit.as_ref()
    }

    /// Report a diagnostic.
    pub fn report(&mut self, id: DiagID, _severity: DiagSeverity, _msg: &str) {
        let mut builder = self.diagnostics.report(id);
        builder.emit();
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// CompilerInvocation — parses command-line args into CompilerOptions
// ═══════════════════════════════════════════════════════════════════════════════

/// Parses command-line arguments into a `CompilerOptions` configuration,
/// then wraps it for use with `CompilerInstance`.
#[derive(Debug, Clone)]
pub struct CompilerInvocation {
    /// The parsed compiler options.
    pub opts: CompilerOptions,
    /// The raw arguments for re-display.
    pub args: Vec<String>,
    /// Program name (argv[0]).
    pub program_name: String,
}

impl CompilerInvocation {
    /// Create from command-line arguments.
    pub fn from_args<I, S>(args: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        let raw: Vec<String> = args.into_iter().map(|s| s.as_ref().to_string()).collect();
        let program_name = raw.first().cloned().unwrap_or_else(|| "clang".to_string());
        let mut opts = CompilerOptions::default();
        let mut i = 1; // skip program name

        // Expand response files.
        let mut expanded = vec![program_name.clone()];
        while i < raw.len() {
            let arg = &raw[i];
            if arg.starts_with('@') {
                let filename = &arg[1..];
                if let Ok(contents) = fs::read_to_string(filename) {
                    for line in contents.lines() {
                        let line = line.trim();
                        if !line.is_empty() && !line.starts_with('#') {
                            expanded.push(line.to_string());
                        }
                    }
                }
            } else {
                expanded.push(arg.clone());
            }
            i += 1;
        }

        // Parse expanded arguments.
        i = 1;
        while i < expanded.len() {
            let arg = &expanded[i];
            match arg.as_str() {
                // ── Output phase ───────────────────────────────────────
                "-E" => {
                    opts.action = FrontendActionKind::PreprocessOnly;
                    opts.preprocess_only = true;
                }
                "-fsyntax-only" => {
                    opts.action = FrontendActionKind::SyntaxOnly;
                    opts.syntax_only = true;
                }
                "-S" => opts.action = FrontendActionKind::EmitAssembly,
                "-c" => opts.action = FrontendActionKind::EmitObj,
                "-emit-llvm" => {
                    opts.action = FrontendActionKind::EmitLLVM;
                    opts.emit_llvm = true;
                }
                "-emit-llvm-bc" => {
                    opts.action = FrontendActionKind::EmitBC;
                    opts.emit_bc = true;
                }
                "-dump-ast" => opts.action = FrontendActionKind::ASTDump,
                "-dump-tokens" => opts.action = FrontendActionKind::DumpTokens,

                // ── Output file ───────────────────────────────────────
                "-o" => {
                    i += 1;
                    if i < expanded.len() {
                        opts.output_file = Some(PathBuf::from(&expanded[i]));
                    }
                }

                // ── Language standard ─────────────────────────────────
                flag if flag.starts_with("-std=") => {
                    let std = &flag[5..];
                    if let Some(cstd) = CLangStandard::from_str(std) {
                        opts.standard = cstd;
                        opts.gnu_extensions = cstd.is_gnu();
                    }
                }
                "-ansi" => opts.standard = CLangStandard::C89,

                // ── Target ────────────────────────────────────────────
                "-target" => {
                    i += 1;
                    if i < expanded.len() {
                        opts.target_triple = expanded[i].clone();
                    }
                }
                flag if flag.starts_with("-target=") => {
                    opts.target_triple = flag[8..].to_string();
                }
                "-march" => {
                    i += 1;
                    if i < expanded.len() {
                        opts.target_cpu = Some(expanded[i].clone());
                    }
                }
                flag if flag.starts_with("-march=") => {
                    opts.target_cpu = Some(flag[7..].to_string());
                }

                // ── Optimization ──────────────────────────────────────
                "-O0" => opts.opt_level = OptLevel::O0,
                "-O1" => opts.opt_level = OptLevel::O1,
                "-O2" => opts.opt_level = OptLevel::O2,
                "-O3" => opts.opt_level = OptLevel::O3,
                "-Os" => opts.opt_level = OptLevel::Os,
                "-Oz" => opts.opt_level = OptLevel::Oz,
                "-g" => opts.debug_info = true,

                // ── Includes ──────────────────────────────────────────
                flag if flag.starts_with("-I") => {
                    let path = if flag.len() > 2 {
                        PathBuf::from(&flag[2..])
                    } else {
                        i += 1;
                        if i < expanded.len() {
                            PathBuf::from(&expanded[i])
                        } else {
                            PathBuf::new()
                        }
                    };
                    if !path.as_os_str().is_empty() {
                        opts.includes.push(path);
                    }
                }

                // ── Defines ───────────────────────────────────────────
                flag if flag.starts_with("-D") => {
                    let def = &flag[2..];
                    if let Some(eq) = def.find('=') {
                        let name = def[..eq].to_string();
                        let val = def[eq + 1..].to_string();
                        opts.defines.push((name, Some(val)));
                    } else {
                        opts.defines.push((def.to_string(), Some("1".to_string())));
                    }
                }

                // ── Undefines ─────────────────────────────────────────
                flag if flag.starts_with("-U") => {
                    let undef = &flag[2..];
                    opts.undefines.push(undef.to_string());
                }

                // ── Warnings ──────────────────────────────────────────
                "-w" => opts.warnings = false,
                "-Wall" => opts.wall = true,
                "-Wextra" => opts.wextra = true,
                "-Wpedantic" | "-pedantic" => opts.pedantic = true,
                "-Werror" => opts.werror = true,
                flag if flag.starts_with("-Wno-") => {
                    opts.wno.push(flag[5..].to_string());
                }
                flag if flag.starts_with("-W")
                    && !flag.starts_with("-Wall")
                    && !flag.starts_with("-Wextra")
                    && !flag.starts_with("-Werror")
                    && !flag.starts_with("-Wno-")
                    && !flag.starts_with("-Wpedantic") =>
                {
                    opts.w.push(flag[2..].to_string());
                }

                // ── Misc flags ────────────────────────────────────────
                "-nostdinc" => opts.nostdinc = true,
                "-nostdinc++" => opts.nostdincpp = true,
                "-fPIC" | "-fpic" => opts.pic = true,
                "-fPIE" | "-fpie" => opts.pie = true,
                "-v" | "--verbose" => opts.verbose = true,
                "--version" => opts.print_version = true,
                "--help" | "-help" => opts.print_help = true,
                "-print-resource-dir" => opts.print_resource_dir = true,
                "-print-search-dirs" => opts.print_search_dirs = true,
                "-dumpmachine" => opts.print_target_triple = true,
                "-x" => {
                    i += 1;
                    if i < expanded.len() {
                        if let Some(lang) = InputLanguage::from_str(&expanded[i]) {
                            opts.lang = lang;
                        }
                    }
                }
                "-include" => {
                    i += 1;
                    if i < expanded.len() {
                        // Pre-include file (for preprocessing).
                        let _ = expanded[i].clone();
                    }
                }
                flag if flag.starts_with("-fstack-protector") => {
                    opts.stack_protector = 1;
                }
                flag if flag.starts_with("-fstack-protector-strong") => {
                    opts.stack_protector = 2;
                }
                flag if flag.starts_with("-fstack-protector-all") => {
                    opts.stack_protector = 3;
                }
                flag if flag.starts_with("-fsanitize=") => {
                    let s = &flag[11..];
                    for part in s.split(',') {
                        opts.sanitize.push(part.to_string());
                    }
                }
                flag if flag.starts_with("-ftls-model=") => {
                    opts.tls_model = flag[12..].to_string();
                }
                flag if flag.starts_with("-f") => {
                    // Unknown -f flags are silently ignored.
                }
                flag if flag.starts_with("-m") => {
                    // Unknown -m flags are silently ignored.
                }

                // ── Input files ───────────────────────────────────────
                arg if !arg.starts_with('-') => {
                    opts.input_files.push(PathBuf::from(arg));
                }

                _ => {
                    // Unknown flags: ignore.
                }
            }
            i += 1;
        }

        CompilerInvocation {
            opts,
            args: raw,
            program_name,
        }
    }

    /// Create a default invocation for simple compilation.
    pub fn default() -> Self {
        Self {
            opts: CompilerOptions::default(),
            args: vec!["clang".to_string()],
            program_name: "clang".to_string(),
        }
    }

    /// Get the output file path (or derive from input).
    pub fn output_file(&self) -> PathBuf {
        if let Some(ref out) = self.opts.output_file {
            return out.clone();
        }
        // Derive from first input file.
        if let Some(input) = self.opts.input_files.first() {
            let stem = input
                .file_stem()
                .unwrap_or_else(|| std::ffi::OsStr::new("a"));
            let ext = match self.opts.action {
                FrontendActionKind::PreprocessOnly => "i",
                FrontendActionKind::EmitLLVM => "ll",
                FrontendActionKind::EmitBC => "bc",
                FrontendActionKind::EmitAssembly => "s",
                FrontendActionKind::EmitObj => "o",
                _ => "out",
            };
            let mut out = PathBuf::from(stem);
            out.set_extension(ext);
            return out;
        }
        PathBuf::from("a.out")
    }
}

impl Default for CompilerInvocation {
    fn default() -> Self {
        Self {
            opts: CompilerOptions::default(),
            args: vec![],
            program_name: "clang".to_string(),
        }
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// CompilationDriver — executes compilation phases in order
// ═══════════════════════════════════════════════════════════════════════════════

/// The compilation driver orchestrates the phased compilation of source files.
///
/// It executes the standard phases: Preprocess → Parse → Sema → CodeGen → Emit,
/// stopping at the phase specified by the `FrontendActionKind`.
#[derive(Debug)]
pub struct CompilationDriver {
    /// The compiler instance.
    pub compiler: CompilerInstance,
    /// The frontend action.
    pub action: FrontendAction,
    /// Phase completion flags.
    phases: CompilationPhases,
}

/// Flags tracking which phases have completed.
#[derive(Debug, Default)]
struct CompilationPhases {
    preprocess_done: bool,
    parse_done: bool,
    sema_done: bool,
    codegen_done: bool,
    emit_done: bool,
}

impl CompilationDriver {
    /// Create a new compilation driver.
    pub fn new(compiler: CompilerInstance, action: FrontendAction) -> Self {
        Self {
            compiler,
            action,
            phases: CompilationPhases::default(),
        }
    }

    /// Create from command-line arguments.
    pub fn from_args<I, S>(args: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        let invocation = CompilerInvocation::from_args(args);
        let action = FrontendAction::for_kind(invocation.opts.action);
        let compiler = CompilerInstance::new(invocation);
        Self::new(compiler, action)
    }

    /// Run the full compilation pipeline.
    pub fn run(&mut self) -> Result<(), Vec<String>> {
        self.preprocess()?;
        self.parse()?;
        self.sema()?;
        self.codegen()?;
        self.emit()?;
        Ok(())
    }

    /// Preprocess only.
    pub fn preprocess(&mut self) -> Result<(), Vec<String>> {
        if self.phases.preprocess_done {
            return Ok(());
        }
        // Preprocessing is handled by the Preprocessor during lexing/parsing.
        // For preprocessing-only mode, run the preprocessor.
        if self.compiler.opts.preprocess_only {
            let fid = self
                .compiler
                .source_manager
                .main_file_id()
                .ok_or_else(|| vec!["no main file for preprocessing".to_string()])?;
            let source = self
                .compiler
                .source_manager
                .get_buffer(fid)
                .ok_or_else(|| vec!["no buffer for main file".to_string()])?;
            let _pp = Preprocessor::new(self.compiler.opts.standard);
            // In a real implementation, collect preprocessed output.
        }
        self.phases.preprocess_done = true;
        Ok(())
    }

    /// Parse only.
    pub fn parse(&mut self) -> Result<(), Vec<String>> {
        if self.phases.parse_done {
            return Ok(());
        }
        if self.compiler.opts.preprocess_only {
            return Ok(());
        }

        let fid = self
            .compiler
            .source_manager
            .main_file_id()
            .ok_or_else(|| vec!["no main file for parsing".to_string()])?;
        let source = self
            .compiler
            .source_manager
            .get_buffer(fid)
            .ok_or_else(|| vec!["no buffer for main file".to_string()])?;

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

    /// Semantic analysis only.
    pub fn sema(&mut self) -> Result<(), Vec<String>> {
        if self.phases.sema_done {
            return Ok(());
        }
        if self.compiler.opts.preprocess_only {
            return Ok(());
        }

        let tu = self
            .compiler
            .translation_unit
            .as_ref()
            .ok_or_else(|| vec!["no AST for semantic analysis".to_string()])?;
        let mut sema = Sema::new(self.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());
        }
        if self.compiler.opts.syntax_only {
            return Ok(());
        }
        self.phases.sema_done = true;
        Ok(())
    }

    /// Code generation only.
    pub fn codegen(&mut self) -> Result<(), Vec<String>> {
        if self.phases.codegen_done {
            return Ok(());
        }
        if self.compiler.opts.preprocess_only || self.compiler.opts.syntax_only {
            return Ok(());
        }

        let tu = self
            .compiler
            .translation_unit
            .as_ref()
            .ok_or_else(|| vec!["no AST for codegen".to_string()])?;
        let mut cg = ClangCodeGen::new("input", &self.compiler.opts.target_triple);
        cg.compile(tu).map_err(|e| {
            e.iter()
                .map(|err| format!("codegen: {}", err))
                .collect::<Vec<_>>()
        })?;
        self.phases.codegen_done = true;
        Ok(())
    }

    /// Emit output.
    pub fn emit(&mut self) -> Result<(), Vec<String>> {
        if self.phases.emit_done {
            return Ok(());
        }
        self.phases.emit_done = true;

        // Emit according to the action kind.
        match &mut self.action {
            FrontendAction::PreprocessOnly(a) => {
                // Already handled.
            }
            FrontendAction::SyntaxOnly(_) => {}
            FrontendAction::EmitLLVM(a) => {
                // TODO: emit LLVM IR text.
            }
            FrontendAction::EmitBC(_) => {
                // TODO: emit LLVM bitcode.
            }
            FrontendAction::EmitAssembly(_) => {
                // TODO: emit assembly text.
            }
            FrontendAction::EmitObj(_) => {
                // TODO: emit object file.
            }
            _ => {}
        }

        Ok(())
    }

    /// Check if a phase is complete.
    pub fn is_preprocess_done(&self) -> bool {
        self.phases.preprocess_done
    }
    pub fn is_parse_done(&self) -> bool {
        self.phases.parse_done
    }
    pub fn is_sema_done(&self) -> bool {
        self.phases.sema_done
    }
    pub fn is_codegen_done(&self) -> bool {
        self.phases.codegen_done
    }
    pub fn is_emit_done(&self) -> bool {
        self.phases.emit_done
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// CompilerInstance — extended diagnostics, preprocessor, AST, sema, codegen
// ═══════════════════════════════════════════════════════════════════════════════

impl CompilerInstance {
    /// Create and configure the diagnostic engine with all options from CompilerOptions.
    ///
    /// Sets up warning flags, error limits, diagnostic output format, and
    /// diagnostic consumer based on compiler options.
    pub fn create_diagnostics(&mut self) -> DiagnosticEngine {
        let mut diag = DiagnosticEngine::new(ClangSourceManager::new());

        // Configure warning/error behavior.
        if self.opts.werror {
            diag.set_warnings_as_errors(true);
        }
        if !self.opts.warnings {
            diag.set_ignore_warnings(true);
        }
        // Note: weverything, wno, and w flags are tracked in self.opts
        // and applied during create_preprocessor and parse/sema phases.

        // Error limit (default: 20).
        diag.set_error_limit(20);

        self.diagnostics = diag;
        DiagnosticEngine::new(ClangSourceManager::new())
    }

    /// Create and configure the preprocessor with the compiler's include paths,
    /// predefined macros, and header search configuration.
    pub fn create_preprocessor(&mut self) -> Preprocessor {
        let mut pp = Preprocessor::new(self.opts.standard);

        // Add predefined macros.
        // __STDC__ and version macros.
        pp.define("__STDC__", "1");
        match self.opts.standard {
            CLangStandard::C89 => {
                pp.define("__STDC_VERSION__", "199409L");
            }
            CLangStandard::C99 | CLangStandard::Gnu99 => {
                pp.define("__STDC_VERSION__", "199901L");
            }
            CLangStandard::C11 | CLangStandard::Gnu11 => {
                pp.define("__STDC_VERSION__", "201112L");
            }
            CLangStandard::C17 | CLangStandard::Gnu17 => {
                pp.define("__STDC_VERSION__", "201710L");
            }
            CLangStandard::C23 => {
                pp.define("__STDC_VERSION__", "202311L");
            }
            _ => {}
        }

        // Architecture and OS defines.
        if self.opts.target_triple.contains("x86_64") {
            pp.define("__x86_64__", "1");
            pp.define("__amd64__", "1");
        }
        if self.opts.target_triple.contains("aarch64") {
            pp.define("__aarch64__", "1");
        }
        if self.opts.target_triple.contains("linux") {
            pp.define("__linux__", "1");
            pp.define("__gnu_linux__", "1");
        }
        if self.opts.target_triple.contains("darwin") || self.opts.target_triple.contains("macos") {
            pp.define("__APPLE__", "1");
        }
        if self.opts.target_triple.contains("windows") || self.opts.target_triple.contains("mingw")
        {
            pp.define("_WIN32", "1");
        }

        // GNU extensions.
        if self.opts.gnu_extensions {
            pp.define("__GNUC__", "4");
            pp.define("__GNUC_MINOR__", "2");
            pp.define("__GNUC_PATCHLEVEL__", "1");
        }

        // Explicit defines from command line.
        for (name, value) in &self.opts.defines {
            let body: String = value.as_deref().unwrap_or("1").to_string();
            pp.define(name, &body);
        }

        // Undefines are tracked but not directly supported by the Preprocessor.
        // In a real implementation, these would be removed from the macro table.

        // Configure include paths.
        for path in &self.opts.includes {
            if let Some(s) = path.to_str() {
                pp.add_include_path(s);
            }
        }
        // System includes use the same mechanism but are tracked separately.
        for path in &self.opts.system_includes {
            if let Some(s) = path.to_str() {
                pp.add_include_path(s);
            }
        }

        // No standard includes flag.
        if self.opts.nostdinc {
            // Clear default include paths that would have been added.
            // In a real implementation, this would disable the built-in search paths.
        }

        pp
    }

    /// Create the AST context with target information.
    ///
    /// The ASTContext holds type information, language options, and
    /// target-specific data needed for semantic analysis.
    pub fn create_ast_context(&mut self) -> ASTContext {
        let lang_opts = LangOptions {
            standard: self.opts.standard,
            gnu_extensions: self.opts.gnu_extensions,
            ms_extensions: self.opts.ms_extensions,
            trigraphs: self.opts.trigraphs,
            digraphs: self.opts.digraphs,
            cxx_mode: false,
        };

        let target_info = TargetInfo {
            triple: self.opts.target_triple.clone(),
            pointer_width: 64,
            size_t_width: 64,
            wchar_width: 32,
            char_is_signed: true,
            int_width: 32,
            long_width: if self.opts.target_triple.contains("windows") {
                32
            } else {
                64
            },
            long_long_width: 64,
            short_width: 16,
            float_width: 32,
            double_width: 64,
            long_double_width: if self.opts.target_triple.contains("x86_64") {
                80
            } else {
                128
            },
            alignof_pointer: 8,
            max_alignment: 16,
            null_pointer_value: 0u64,
            user_label_prefix: String::new(),
        };

        ASTContext::new(lang_opts, target_info)
    }

    /// Create and initialize the semantic analyzer.
    pub fn create_sema(&mut self) -> Sema {
        Sema::new(self.opts.standard)
    }

    /// Create a code generator with a TargetMachine for the configured target.
    pub fn create_codegen(&self) -> ClangCodeGen<'_> {
        ClangCodeGen::new("input", &self.opts.target_triple)
    }

    /// Create a code generator with a specific module name.
    pub fn create_codegen_named(&self, module_name: &str) -> ClangCodeGen<'_> {
        ClangCodeGen::new(module_name, &self.opts.target_triple)
    }

    /// Execute a frontend action from beginning to end.
    ///
    /// This is the main entry point for running any FrontendAction.
    /// It orchestrates the full compilation flow:
    /// 1. BeginSourceFile — sets up source, preprocessor, AST
    /// 2. Execute — runs parse + sema + codegen + emit phases
    /// 3. EndSourceFile — cleanup and flush diagnostics
    pub fn execute_action(&mut self, action: &mut FrontendAction) -> Result<(), Vec<String>> {
        // Phase 1: Begin source file.
        self.begin_source_file(action)?;

        // Phase 2: Execute the action.
        action.execute()?;

        // Phase 3: End source file.
        self.end_source_file()?;

        Ok(())
    }

    /// Execute a frontend action with full error recovery.
    ///
    /// Unlike execute_action, this method attempts to continue after
    /// non-fatal errors and collects all diagnostics.
    pub fn execute_action_with_recovery(
        &mut self,
        action: &mut FrontendAction,
    ) -> (bool, Vec<String>) {
        let mut errors: Vec<String> = Vec::new();

        // Try to begin source file.
        match self.begin_source_file(action) {
            Ok(()) => {}
            Err(e) => {
                errors.extend(e);
                return (false, errors);
            }
        }

        // Try to execute.
        match action.execute() {
            Ok(()) => {}
            Err(e) => {
                errors.extend(e);
            }
        }

        // Always try to end source file.
        if let Err(e) = self.end_source_file() {
            errors.extend(e);
        }

        (errors.is_empty(), errors)
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// ASTContext — Holds type and target information for semantic analysis
// ═══════════════════════════════════════════════════════════════════════════════

/// Language options that configure parsing and semantic analysis behavior.
#[derive(Debug, Clone)]
pub struct LangOptions {
    pub standard: CLangStandard,
    pub gnu_extensions: bool,
    pub ms_extensions: bool,
    pub trigraphs: bool,
    pub digraphs: bool,
    pub cxx_mode: bool,
}

impl Default for LangOptions {
    fn default() -> Self {
        Self {
            standard: CLangStandard::C17,
            gnu_extensions: false,
            ms_extensions: false,
            trigraphs: false,
            digraphs: true,
            cxx_mode: false,
        }
    }
}

/// Target-specific information used by the AST and code generator.
#[derive(Debug, Clone)]
pub struct TargetInfo {
    pub triple: String,
    pub pointer_width: u32,
    pub size_t_width: u32,
    pub wchar_width: u32,
    pub char_is_signed: bool,
    pub int_width: u32,
    pub long_width: u32,
    pub long_long_width: u32,
    pub short_width: u32,
    pub float_width: u32,
    pub double_width: u32,
    pub long_double_width: u32,
    pub alignof_pointer: u32,
    pub max_alignment: u32,
    pub null_pointer_value: u64,
    pub user_label_prefix: String,
}

impl TargetInfo {
    /// Create a default target info for x86_64 Linux.
    pub fn default_x86_64_linux() -> Self {
        Self {
            triple: "x86_64-unknown-linux-gnu".to_string(),
            pointer_width: 64,
            size_t_width: 64,
            wchar_width: 32,
            char_is_signed: true,
            int_width: 32,
            long_width: 64,
            long_long_width: 64,
            short_width: 16,
            float_width: 32,
            double_width: 64,
            long_double_width: 80,
            alignof_pointer: 8,
            max_alignment: 16,
            null_pointer_value: 0,
            user_label_prefix: String::new(),
        }
    }

    /// Create target info for aarch64 Linux.
    pub fn default_aarch64_linux() -> Self {
        Self {
            triple: "aarch64-unknown-linux-gnu".to_string(),
            pointer_width: 64,
            size_t_width: 64,
            wchar_width: 32,
            char_is_signed: false,
            int_width: 32,
            long_width: 64,
            long_long_width: 64,
            short_width: 16,
            float_width: 32,
            double_width: 64,
            long_double_width: 128,
            alignof_pointer: 8,
            max_alignment: 16,
            null_pointer_value: 0,
            user_label_prefix: String::new(),
        }
    }

    /// Get the width of the specified integer type in bits.
    pub fn get_type_width(&self, ty: &str) -> Option<u32> {
        match ty {
            "char" => Some(8),
            "short" => Some(self.short_width),
            "int" => Some(self.int_width),
            "long" => Some(self.long_width),
            "long long" => Some(self.long_long_width),
            "float" => Some(self.float_width),
            "double" => Some(self.double_width),
            "long double" => Some(self.long_double_width),
            "pointer" | "size_t" => Some(self.pointer_width),
            "wchar_t" => Some(self.wchar_width),
            _ => None,
        }
    }

    /// Get the alignment of the specified type in bytes.
    pub fn get_type_align(&self, ty: &str) -> Option<u32> {
        let width = self.get_type_width(ty)?;
        Some((width + 7) / 8)
    }

    /// Get pointer width in bytes.
    pub fn pointer_width_bytes(&self) -> u32 {
        self.pointer_width / 8
    }

    /// Is this target little-endian?
    pub fn is_little_endian(&self) -> bool {
        // All supported targets are little-endian for now.
        true
    }
}

impl Default for TargetInfo {
    fn default() -> Self {
        Self::default_x86_64_linux()
    }
}

/// The AST context holds all type information and target data for a compilation.
#[derive(Debug, Clone)]
pub struct ASTContext {
    pub lang_opts: LangOptions,
    pub target_info: TargetInfo,
    pub types: Vec<QualType>,
    pub type_names: Vec<String>,
    pub builtin_types_initialized: bool,
}

impl ASTContext {
    /// Create a new AST context with the given language options and target info.
    pub fn new(lang_opts: LangOptions, target_info: TargetInfo) -> Self {
        let mut ctx = Self {
            lang_opts,
            target_info,
            types: Vec::new(),
            type_names: Vec::new(),
            builtin_types_initialized: false,
        };
        ctx.initialize_builtin_types();
        ctx
    }

    /// Initialize the built-in types.
    fn initialize_builtin_types(&mut self) {
        if self.builtin_types_initialized {
            return;
        }
        self.builtin_types_initialized = true;

        // Initialize all standard C types.
        self.types.push(QualType::void());
        self.type_names.push("void".to_string());

        self.types.push(QualType::char_type());
        self.type_names.push("char".to_string());

        self.types.push(QualType::schar());
        self.type_names.push("signed char".to_string());

        self.types.push(QualType::uchar());
        self.type_names.push("unsigned char".to_string());

        self.types.push(QualType::short_type());
        self.type_names.push("short".to_string());

        self.types.push(QualType::ushort());
        self.type_names.push("unsigned short".to_string());

        self.types.push(QualType::int());
        self.type_names.push("int".to_string());

        self.types.push(QualType::uint());
        self.type_names.push("unsigned int".to_string());

        self.types.push(QualType::long_type());
        self.type_names.push("long".to_string());

        self.types.push(QualType::ulong());
        self.type_names.push("unsigned long".to_string());

        self.types.push(QualType::long_long());
        self.type_names.push("long long".to_string());

        self.types.push(QualType::ulong_long());
        self.type_names.push("unsigned long long".to_string());

        self.types.push(QualType::float_type());
        self.type_names.push("float".to_string());

        self.types.push(QualType::double_type());
        self.type_names.push("double".to_string());

        self.types.push(QualType::long_double());
        self.type_names.push("long double".to_string());
    }

    /// Look up a type by its name.
    pub fn lookup_type(&self, name: &str) -> Option<&QualType> {
        self.type_names
            .iter()
            .position(|n| n == name)
            .map(|i| &self.types[i])
    }

    /// Get the size of a type in bits.
    pub fn get_type_size(&self, ty: &QualType) -> u32 {
        // Use target info for type sizing.
        if ty.is_void() {
            return 0;
        }
        if ty.is_pointer() {
            return self.target_info.pointer_width;
        }
        if ty.is_integer() {
            if ty.is_char() {
                return 8;
            }
            if ty.is_short() {
                return self.target_info.short_width;
            }
            if ty.is_int() {
                return self.target_info.int_width;
            }
            if ty.is_long() {
                return self.target_info.long_width;
            }
            if ty.is_long_long() {
                return self.target_info.long_long_width;
            }
            return 32;
        }
        if ty.is_floating() {
            if ty.is_float() {
                return self.target_info.float_width;
            }
            if ty.is_double() {
                return self.target_info.double_width;
            }
            return self.target_info.long_double_width;
        }
        32
    }

    /// Get the alignment of a type in bits.
    pub fn get_type_align(&self, ty: &QualType) -> u32 {
        let size = self.get_type_size(ty);
        if size >= 128 {
            128
        } else if size >= 64 {
            64
        } else if size >= 32 {
            32
        } else if size >= 16 {
            16
        } else {
            8
        }
    }
}

impl Default for ASTContext {
    fn default() -> Self {
        Self::new(LangOptions::default(), TargetInfo::default())
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// ParseAST — parse the entire translation unit and feed to ASTConsumer
// ═══════════════════════════════════════════════════════════════════════════════

/// Parse an entire translation unit from source and feed each top-level
/// declaration to the given AST consumer.
///
/// This is the primary entry point for AST-based compilation.
/// It runs lexical analysis, preprocessing, and parsing, then calls
/// `HandleTopLevelDecl` on the consumer for each declaration.
pub fn parse_ast(
    consumer: &mut dyn ASTConsumer,
    source: &str,
    standard: CLangStandard,
) -> Result<TranslationUnit, Vec<String>> {
    let tokens = lexer::tokenize(source, standard);
    let mut parser = parser::Parser::new(&tokens, standard);
    let tu = parser.parse().map_err(|e| {
        e.into_iter()
            .map(|err| format!("parse error: {}", err))
            .collect::<Vec<_>>()
    })?;

    // Notify consumer of translation unit begin.
    consumer.handle_translation_unit_begin(&tu);

    // Feed each top-level declaration to the consumer.
    for decl in &tu.decls {
        consumer.handle_top_level_decl(decl);
    }

    // Notify consumer of translation unit end.
    consumer.handle_translation_unit_end(&tu);

    Ok(tu)
}

/// Parse with semantic analysis, feeding results to a consumer.
pub fn parse_and_sema_ast(
    consumer: &mut dyn ASTConsumer,
    source: &str,
    standard: CLangStandard,
) -> Result<TranslationUnit, Vec<String>> {
    // Parse.
    let tokens = lexer::tokenize(source, standard);
    let mut parser = parser::Parser::new(&tokens, standard);
    let tu = parser.parse().map_err(|e| {
        e.into_iter()
            .map(|err| format!("parse error: {}", err))
            .collect::<Vec<_>>()
    })?;

    // Semantic analysis.
    let mut sema = Sema::new(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());
    }

    // Feed to consumer.
    consumer.handle_translation_unit_begin(&tu);
    for decl in &tu.decls {
        consumer.handle_top_level_decl(decl);
    }
    consumer.handle_translation_unit_end(&tu);

    Ok(tu)
}

// ═══════════════════════════════════════════════════════════════════════════════
// CodeGenAction — parse→sema→codegen→emit with error checking
// ═══════════════════════════════════════════════════════════════════════════════

/// A frontend action that performs code generation.
///
/// CodeGenAction runs the full parse→sema→codegen pipeline and
/// optionally emits the result in various formats.
#[derive(Debug)]
pub struct CodeGenAction {
    /// The LLVM module produced by code generation.
    pub module: Option<Module>,
    /// The kind of output to produce.
    pub output_kind: OutputFormat,
    /// The target triple.
    pub triple: String,
    /// Optional output file path.
    pub output_file: Option<PathBuf>,
    /// Whether to verify the module after codegen.
    pub verify_module: bool,
    /// Collected diagnostics during codegen.
    pub diagnostics: Vec<String>,
    /// Whether codegen succeeded.
    pub succeeded: bool,
}

impl CodeGenAction {
    /// Create a new codegen action for the given output format.
    pub fn new(output_kind: OutputFormat, triple: &str) -> Self {
        Self {
            module: None,
            output_kind,
            triple: triple.to_string(),
            output_file: None,
            verify_module: true,
            diagnostics: Vec::new(),
            succeeded: false,
        }
    }

    /// Set the output file path.
    pub fn set_output_file(&mut self, path: PathBuf) {
        self.output_file = Some(path);
    }

    /// Execute the codegen action: parse → sema → codegen → emit.
    pub fn execute_action(
        &mut self,
        source: &str,
        standard: CLangStandard,
    ) -> Result<(), Vec<String>> {
        // Phase 1: Lex and parse.
        let tokens = lexer::tokenize(source, standard);
        let mut parser = parser::Parser::new(&tokens, standard);
        let tu = parser.parse().map_err(|e| {
            let errs: Vec<String> = e
                .into_iter()
                .map(|err| format!("parse error: {}", err))
                .collect();
            self.diagnostics.extend(errs.clone());
            errs
        })?;

        // Phase 2: Semantic analysis.
        let mut sema = Sema::new(standard);
        sema.analyze(&tu).map_err(|e| {
            let errs: Vec<String> = e.iter().map(|err| format!("sema error: {}", err)).collect();
            self.diagnostics.extend(errs.clone());
            errs
        })?;
        if sema.has_errors() {
            self.diagnostics.extend(sema.errors.clone());
            return Err(sema.errors.clone());
        }

        // Phase 3: Code generation.
        let mut cg = ClangCodeGen::new("input", &self.triple);
        cg.compile(&tu).map_err(|e| {
            let errs: Vec<String> = e
                .iter()
                .map(|err| format!("codegen error: {}", err))
                .collect();
            self.diagnostics.extend(errs.clone());
            errs
        })?;

        // Phase 4: Verify the module.
        if self.verify_module {
            // In a real implementation, we'd use LLVM's verifier.
            // For now, we just note that verification was requested.
        }

        self.module = Some(cg.module);
        self.succeeded = true;

        // Phase 5: Emit output based on output kind.
        match self.output_kind {
            OutputFormat::LLVM_IR => {
                // Emit .ll text.
                if let Some(ref module) = self.module {
                    let _ir = format!("; ModuleID = '{}'\n", module.name);
                }
            }
            OutputFormat::LLVM_BC => {
                // Emit .bc bitcode.
                // Bitcode serialization would go here.
            }
            OutputFormat::Assembly => {
                // Emit .s assembly.
                // TargetMachine assembly emission would go here.
            }
            OutputFormat::Object => {
                // Emit .o object file.
                // TargetMachine object emission would go here.
            }
            OutputFormat::Executable | OutputFormat::SharedLib => {
                // Linking phase would be handled by the driver.
            }
            _ => {}
        }

        Ok(())
    }

    /// Get the produced LLVM module.
    pub fn get_module(&self) -> Option<&Module> {
        self.module.as_ref()
    }

    /// Check if codegen succeeded.
    pub fn is_successful(&self) -> bool {
        self.succeeded
    }

    /// Get all collected diagnostics.
    pub fn get_diagnostics(&self) -> &[String] {
        &self.diagnostics
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// EmitObjAction — codegen → TargetMachine → object file (.o output)
// ═══════════════════════════════════════════════════════════════════════════════

/// An action that produces an object file from source code.
///
/// Runs the full pipeline: lex→parse→sema→codegen→TargetMachine→.o
#[derive(Debug)]
pub struct EmitObjActionFull {
    /// The target triple.
    pub triple: String,
    /// Output file path.
    pub output_file: PathBuf,
    /// Optimization level.
    pub opt_level: OptLevel,
    /// Whether to include debug info.
    pub debug_info: bool,
    /// The resulting object bytes.
    pub object_bytes: Option<Vec<u8>>,
    /// Whether the action completed successfully.
    pub completed: bool,
}

impl EmitObjActionFull {
    /// Create a new object file emission action.
    pub fn new(triple: &str, output_file: PathBuf, opt_level: OptLevel) -> Self {
        Self {
            triple: triple.to_string(),
            output_file,
            opt_level,
            debug_info: false,
            object_bytes: None,
            completed: false,
        }
    }

    /// Set debug info flag.
    pub fn set_debug_info(&mut self, debug: bool) {
        self.debug_info = debug;
    }

    /// Execute the action: compile source to object bytes.
    pub fn execute(
        &mut self,
        source: &str,
        standard: CLangStandard,
    ) -> Result<Vec<u8>, Vec<String>> {
        // Lex and parse.
        let tokens = lexer::tokenize(source, standard);
        let mut parser = parser::Parser::new(&tokens, standard);
        let tu = parser.parse().map_err(|e| {
            e.into_iter()
                .map(|err| format!("parse error: {}", err))
                .collect::<Vec<_>>()
        })?;

        // Semantic analysis.
        let mut sema = Sema::new(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 mut cg = ClangCodeGen::new("input", &self.triple);
        cg.compile(&tu).map_err(|e| {
            e.iter()
                .map(|err| format!("codegen error: {}", err))
                .collect::<Vec<_>>()
        })?;

        // Emit object file through TargetMachine.
        // In a real implementation:
        // 1. Create TargetMachine with self.triple, self.opt_level
        // 2. Run optimization passes
        // 3. Emit object bytes via MC layer
        //
        // For now, return placeholder object bytes.
        let obj = self.emit_object(&cg.module)?;
        self.object_bytes = Some(obj.clone());
        self.completed = true;

        // Write to file if output file is set.
        if !self.output_file.as_os_str().is_empty() {
            if let Some(ref bytes) = self.object_bytes {
                std::fs::write(&self.output_file, bytes)
                    .map_err(|e| vec![format!("failed to write object file: {}", e)])?;
            }
        }

        Ok(obj)
    }

    /// Emit object bytes from the LLVM module through the TargetMachine.
    fn emit_object(&self, _module: &Module) -> Result<Vec<u8>, Vec<String>> {
        // In a full implementation, this would:
        // 1. Create an LLVMTargetMachine for the triple
        // 2. Add optimization passes if self.opt_level > O0
        // 3. Use LLVM's object streamer to emit machine code
        //
        // For now, return a minimal ELF header as placeholder.
        let mut obj = Vec::new();

        // Minimal ELF64 header.
        obj.extend_from_slice(&[0x7f, b'E', b'L', b'F']); // ELF magic
        obj.push(2); // 64-bit
        obj.push(1); // Little-endian
        obj.push(1); // ELF version
        obj.push(0); // System V ABI
        obj.push(0); // ABI version
        obj.extend_from_slice(&[0; 7]); // Padding
        obj.extend_from_slice(&[2, 0]); // ET_EXEC (little-endian)
        obj.extend_from_slice(&[0x3e, 0]); // x86_64
        obj.extend_from_slice(&[1, 0, 0, 0]); // ELF version
                                              // Entry point, program header, section header offsets (zeroed).
        obj.extend_from_slice(&[0; 8 + 8 + 4]);
        obj.extend_from_slice(&[64, 0]); // ELF header size
        obj.extend_from_slice(&[56, 0]); // Program header size
        obj.extend_from_slice(&[0, 0]); // Number of program headers
        obj.extend_from_slice(&[64, 0]); // Section header size
        obj.extend_from_slice(&[0, 0]); // Number of section headers
        obj.extend_from_slice(&[0, 0]); // Section header string table index

        Ok(obj)
    }

    /// Get the object bytes.
    pub fn get_object_bytes(&self) -> Option<&[u8]> {
        self.object_bytes.as_deref()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// EmitAssemblyAction — codegen → TargetMachine → assembly (.s output)
// ═══════════════════════════════════════════════════════════════════════════════

/// An action that produces assembly text from source code.
#[derive(Debug)]
pub struct EmitAssemblyActionFull {
    /// The target triple.
    pub triple: String,
    /// Output file path.
    pub output_file: PathBuf,
    /// Optimization level.
    pub opt_level: OptLevel,
    /// The resulting assembly text.
    pub assembly_text: Option<String>,
    /// Whether the action completed successfully.
    pub completed: bool,
}

impl EmitAssemblyActionFull {
    /// Create a new assembly emission action.
    pub fn new(triple: &str, output_file: PathBuf, opt_level: OptLevel) -> Self {
        Self {
            triple: triple.to_string(),
            output_file,
            opt_level,
            assembly_text: None,
            completed: false,
        }
    }

    /// Execute the action: compile source to assembly.
    pub fn execute(
        &mut self,
        source: &str,
        standard: CLangStandard,
    ) -> Result<String, Vec<String>> {
        let tokens = lexer::tokenize(source, standard);
        let mut parser = parser::Parser::new(&tokens, standard);
        let tu = parser.parse().map_err(|e| {
            e.into_iter()
                .map(|err| format!("parse error: {}", err))
                .collect::<Vec<_>>()
        })?;

        let mut sema = Sema::new(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());
        }

        let mut cg = ClangCodeGen::new("input", &self.triple);
        cg.compile(&tu).map_err(|e| {
            e.iter()
                .map(|err| format!("codegen error: {}", err))
                .collect::<Vec<_>>()
        })?;

        // Emit assembly through TargetMachine.
        let asm = self.emit_assembly(&cg.module)?;
        self.assembly_text = Some(asm.clone());
        self.completed = true;

        // Write to file.
        if !self.output_file.as_os_str().is_empty() {
            if let Some(ref text) = self.assembly_text {
                std::fs::write(&self.output_file, text)
                    .map_err(|e| vec![format!("failed to write assembly file: {}", e)])?;
            }
        }

        Ok(asm)
    }

    /// Emit assembly text from the LLVM module.
    fn emit_assembly(&self, module: &Module) -> Result<String, Vec<String>> {
        let mut asm = String::new();
        asm.push_str(&format!("\t.text\n"));
        asm.push_str(&format!("\t.file\t\"{}\"\n", module.name));

        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", func.name, func.name));
        }

        if module.functions.is_empty() {
            asm.push_str("\t; empty module\n");
        }

        Ok(asm)
    }

    /// Get the assembly text.
    pub fn get_assembly(&self) -> Option<&str> {
        self.assembly_text.as_deref()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// EmitLLVMActionFull — codegen → Module → .ll text output
// ═══════════════════════════════════════════════════════════════════════════════

/// An action that produces LLVM IR text from source code.
#[derive(Debug)]
pub struct EmitLLVMActionFull {
    /// The target triple.
    pub triple: String,
    /// Output file path.
    pub output_file: PathBuf,
    /// Optimization level.
    pub opt_level: OptLevel,
    /// The resulting IR text.
    pub ir_text: Option<String>,
    /// Whether the action completed successfully.
    pub completed: bool,
}

impl EmitLLVMActionFull {
    /// Create a new LLVM IR emission action.
    pub fn new(triple: &str, output_file: PathBuf) -> Self {
        Self {
            triple: triple.to_string(),
            output_file,
            opt_level: OptLevel::O0,
            ir_text: None,
            completed: false,
        }
    }

    /// Execute the action: compile source to LLVM IR.
    pub fn execute(
        &mut self,
        source: &str,
        standard: CLangStandard,
    ) -> Result<String, Vec<String>> {
        let tokens = lexer::tokenize(source, standard);
        let mut parser = parser::Parser::new(&tokens, standard);
        let tu = parser.parse().map_err(|e| {
            e.into_iter()
                .map(|err| format!("parse error: {}", err))
                .collect::<Vec<_>>()
        })?;

        let mut sema = Sema::new(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());
        }

        let mut cg = ClangCodeGen::new("input", &self.triple);
        cg.compile(&tu).map_err(|e| {
            e.iter()
                .map(|err| format!("codegen error: {}", err))
                .collect::<Vec<_>>()
        })?;

        let ir = self.emit_ir(&cg.module);
        self.ir_text = Some(ir.clone());
        self.completed = true;

        // Write to file.
        if !self.output_file.as_os_str().is_empty() {
            if let Some(ref text) = self.ir_text {
                std::fs::write(&self.output_file, text)
                    .map_err(|e| vec![format!("failed to write IR file: {}", e)])?;
            }
        }

        Ok(ir)
    }

    /// Emit LLVM IR text from the module.
    fn emit_ir(&self, module: &Module) -> String {
        let mut ir = String::new();
        ir.push_str(&format!("; ModuleID = '{}'\n", module.name));
        ir.push_str(&format!("source_filename = \"{}\"\n", module.name));
        ir.push_str(&format!("target triple = \"{}\"\n", self.triple));

        // Emit data layout string.
        ir.push_str("target datalayout = \"e-m:e-p270:32:32-p271:32:32-p272:64:64-i64:64-f80:128-n8:16:32:64-S128\"\n");
        ir.push_str("\n");

        // Emit global variables.
        for gv in &module.globals {
            let gv = gv.borrow();
            ir.push_str(&format!("@{} = ", gv.name));
            if gv.is_constant {
                ir.push_str("constant ");
            } else {
                ir.push_str("global ");
            }
            if let Some(ref init) = gv.initializer {
                ir.push_str(&format!("{}", init.borrow().name));
            } else {
                ir.push_str("zeroinitializer");
            }
            ir.push_str("\n");
        }
        if !module.globals.is_empty() {
            ir.push_str("\n");
        }

        // Emit function declarations.
        for decl in &module.declarations {
            let decl = decl.borrow();
            ir.push_str(&format!(
                "declare {} @{}(",
                decl.return_type
                    .as_ref()
                    .map(|t| t.to_string())
                    .unwrap_or_else(|| "void".to_string()),
                decl.name
            ));
            for (i, param) in decl.params.iter().enumerate() {
                if i > 0 {
                    ir.push_str(", ");
                }
                ir.push_str(&format!("{}", param));
            }
            if decl.is_vararg {
                if !decl.params.is_empty() {
                    ir.push_str(", ");
                }
                ir.push_str("...");
            }
            ir.push_str(")\n");
        }
        if !module.declarations.is_empty() {
            ir.push_str("\n");
        }

        // Emit function definitions.
        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();
                if !bb.name.is_empty() {
                    ir.push_str(&format!("{}:\n", bb.name));
                } else {
                    ir.push_str("entry:\n");
                }
                for inst in &bb.instructions {
                    let inst = inst.borrow();
                    if let Some(ref result) = inst.result {
                        ir.push_str(&format!("  %{} = {:?}", result, inst.opcode));
                    } else {
                        ir.push_str(&format!("  {:?}", inst.opcode));
                    }
                    ir.push_str("\n");
                }
            }
            ir.push_str("}\n\n");
        }

        // Emit module-level metadata.
        ir.push_str(&format!("!llvm.module.flags = !{{!0}}\n"));
        ir.push_str(&format!(
            "!0 = !{{i32 2, !\"Debug Info Version\", i32 3}}\n"
        ));

        ir
    }

    /// Get the IR text.
    pub fn get_ir(&self) -> Option<&str> {
        self.ir_text.as_deref()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// EmitBCActionFull — codegen → Module → .bc bitcode output
// ═══════════════════════════════════════════════════════════════════════════════

/// An action that produces LLVM bitcode from source code.
#[derive(Debug)]
pub struct EmitBCActionFull {
    /// The target triple.
    pub triple: String,
    /// Output file path.
    pub output_file: PathBuf,
    /// The resulting bitcode bytes.
    pub bitcode_bytes: Option<Vec<u8>>,
    /// Whether the action completed successfully.
    pub completed: bool,
}

impl EmitBCActionFull {
    /// Create a new bitcode emission action.
    pub fn new(triple: &str, output_file: PathBuf) -> Self {
        Self {
            triple: triple.to_string(),
            output_file,
            bitcode_bytes: None,
            completed: false,
        }
    }

    /// Execute the action: compile source to LLVM bitcode.
    pub fn execute(
        &mut self,
        source: &str,
        standard: CLangStandard,
    ) -> Result<Vec<u8>, Vec<String>> {
        let tokens = lexer::tokenize(source, standard);
        let mut parser = parser::Parser::new(&tokens, standard);
        let tu = parser.parse().map_err(|e| {
            e.into_iter()
                .map(|err| format!("parse error: {}", err))
                .collect::<Vec<_>>()
        })?;

        let mut sema = Sema::new(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());
        }

        let mut cg = ClangCodeGen::new("input", &self.triple);
        cg.compile(&tu).map_err(|e| {
            e.iter()
                .map(|err| format!("codegen error: {}", err))
                .collect::<Vec<_>>()
        })?;

        let bc = self.emit_bitcode(&cg.module);
        self.bitcode_bytes = Some(bc.clone());
        self.completed = true;

        // Write to file.
        if !self.output_file.as_os_str().is_empty() {
            if let Some(ref bytes) = self.bitcode_bytes {
                std::fs::write(&self.output_file, bytes)
                    .map_err(|e| vec![format!("failed to write bitcode file: {}", e)])?;
            }
        }

        Ok(bc)
    }

    /// Emit bitcode bytes from the LLVM module.
    fn emit_bitcode(&self, _module: &Module) -> Vec<u8> {
        // LLVM bitcode format (simplified wrapper).
        let mut bc = Vec::new();

        // Magic number for LLVM IR bitcode (0xDEC0DEC0 or 0x0B17C0DE).
        // Real implementation would use LLVM's BitcodeWriter.
        bc.extend_from_slice(&[0xDE, 0xC0, 0x17, 0x0B]); // "BC\xC0\xDE"

        // Placeholder bitcode content.
        // A real implementation would serialize the module using
        // LLVM's bitcode format with block structure:
        // - BLOCKINFO_BLOCK
        // - MODULE_BLOCK
        //   - TYPE_BLOCK
        //   - PARAMATTR_BLOCK
        //   - FUNCTION_BLOCK
        //     - CONSTANTS_BLOCK
        //     - VALUE_SYMTAB_BLOCK
        //     - METADATA_BLOCK

        bc.extend_from_slice(&[0; 64]); // Placeholder content

        bc
    }

    /// Get the bitcode bytes.
    pub fn get_bitcode(&self) -> Option<&[u8]> {
        self.bitcode_bytes.as_deref()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// FrontendAction — full initialize/execute/cleanup lifecycle
// ═══════════════════════════════════════════════════════════════════════════════

/// Extended FrontendAction with full lifecycle management.
///
/// Implements BeginSourceFile → Execute → EndSourceFile with proper
/// initialization of source, preprocessor, AST, and code generation.
impl FrontendAction {
    /// Begin processing a source file: initialize source manager,
    /// preprocessor, and AST context.
    pub fn begin_source_file_full(
        &mut self,
        source: &str,
        compiler: &mut CompilerInstance,
    ) -> Result<(), Vec<String>> {
        // Load the source into the source manager.
        let _fid = compiler
            .source_manager
            .load_virtual_file("<input>", source.to_string())
            .map_err(|e| vec![format!("failed to load source: {}", e)])?;

        // Create preprocessor with command-line defines and includes.
        let _pp = compiler.create_preprocessor();

        // Create AST context with target and language options.
        let _ast_ctx = compiler.create_ast_context();

        Ok(())
    }

    /// Execute the action: run parse + sema + codegen + emit phases.
    pub fn execute_full(
        &mut self,
        source: &str,
        compiler: &mut CompilerInstance,
    ) -> Result<(), Vec<String>> {
        match self {
            FrontendAction::PreprocessOnly(action) => {
                action.execute();
                Ok(())
            }
            FrontendAction::SyntaxOnly(_) => {
                let tokens = lexer::tokenize(source, compiler.opts.standard);
                let mut parser = parser::Parser::new(&tokens, compiler.opts.standard);
                let tu = parser.parse().map_err(|e| {
                    e.into_iter()
                        .map(|err| format!("parse error: {}", err))
                        .collect::<Vec<_>>()
                })?;
                let mut sema = Sema::new(compiler.opts.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());
                }
                Ok(())
            }
            FrontendAction::EmitLLVM(action) => {
                action.execute();
                Ok(())
            }
            FrontendAction::EmitBC(action) => {
                action.execute();
                Ok(())
            }
            FrontendAction::EmitAssembly(action) => {
                action.execute();
                Ok(())
            }
            FrontendAction::EmitObj(action) => {
                action.execute();
                Ok(())
            }
            FrontendAction::ASTDump(_) => {
                let tokens = lexer::tokenize(source, compiler.opts.standard);
                let mut parser = parser::Parser::new(&tokens, compiler.opts.standard);
                let tu = parser.parse().map_err(|e| {
                    e.into_iter()
                        .map(|err| format!("parse error: {}", err))
                        .collect::<Vec<_>>()
                })?;
                // Dump AST.
                for decl in &tu.decls {
                    eprintln!("{}", decl);
                }
                Ok(())
            }
            FrontendAction::DumpTokens(_) => {
                let tokens = lexer::tokenize(source, compiler.opts.standard);
                for tok in &tokens {
                    eprintln!("{} {:?}", tok.location.line, tok.kind);
                }
                Ok(())
            }
        }
    }

    /// End source file processing: cleanup, flush diagnostics.
    pub fn end_source_file_full(
        &mut self,
        compiler: &mut CompilerInstance,
    ) -> Result<(), Vec<String>> {
        // Flush any pending diagnostics.
        // In a real implementation, this would flush the diagnostic consumer.

        // Reset compiler state.
        compiler.source_file_begun = false;

        // Call action-specific cleanup.
        self.end_source_file()?;

        Ok(())
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// MultiplexConsumer — dispatch HandleTranslationUnit to all sub-consumers
// ═══════════════════════════════════════════════════════════════════════════════

impl MultiplexConsumer {
    /// Create a multiplex consumer that dispatches to all given sub-consumers.
    pub fn create(consumers: Vec<Box<dyn ASTConsumer>>) -> Self {
        Self { consumers }
    }

    /// Dispatch the entire translation unit to all sub-consumers at once.
    ///
    /// This is called when the full TU is available and all consumers
    /// should process it simultaneously.
    pub fn handle_translation_unit(&mut self, tu: &TranslationUnit) {
        for consumer in &mut self.consumers {
            consumer.handle_translation_unit_begin(tu);
            for decl in &tu.decls {
                consumer.handle_top_level_decl(decl);
            }
            consumer.handle_translation_unit_end(tu);
        }
    }

    /// Finish all sub-consumers.
    pub fn finish_all(&mut self) {
        for consumer in &mut self.consumers {
            consumer.finish();
        }
    }

    /// Print stats from all sub-consumers.
    pub fn print_all_stats(&self) {
        for consumer in &self.consumers {
            consumer.print_stats();
        }
    }

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

    /// Check if the multiplexer has any consumers.
    pub fn is_empty(&self) -> bool {
        self.consumers.is_empty()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// VerifyDiagnosticConsumer — check that expected diagnostics are emitted
// ═══════════════════════════════════════════════════════════════════════════════

/// A diagnostic consumer that verifies expected diagnostics are produced.
///
/// Used primarily in testing to assert that the compiler produces
/// specific errors and warnings for given inputs.
#[derive(Debug)]
pub struct VerifyDiagnosticConsumer {
    /// Expected diagnostics to check for.
    pub expected: Vec<ExpectedDiagnostic>,
    /// Actual diagnostics received.
    pub received: Vec<ReceivedDiagnostic>,
    /// Whether the consumer should fail on unexpected diagnostics.
    pub strict: bool,
    /// Additional diagnostics that are expected but optional.
    pub optional: Vec<ExpectedDiagnostic>,
}

/// An expected diagnostic with location and message pattern.
#[derive(Debug, Clone)]
pub struct ExpectedDiagnostic {
    /// The severity level expected.
    pub severity: DiagSeverity,
    /// The file name where the diagnostic is expected.
    pub file: Option<String>,
    /// The line number where the diagnostic is expected (0 = any line).
    pub line: u32,
    /// The column where the diagnostic is expected (0 = any column).
    pub column: u32,
    /// A substring that should appear in the diagnostic message.
    pub message_contains: Option<String>,
    /// The exact expected message.
    pub message_exact: Option<String>,
    /// Whether this diagnostic has been seen.
    pub seen: bool,
}

impl ExpectedDiagnostic {
    /// Create an expected error on a specific line.
    pub fn error_on_line(line: u32, msg: &str) -> Self {
        Self {
            severity: DiagSeverity::Error,
            file: None,
            line,
            column: 0,
            message_contains: Some(msg.to_string()),
            message_exact: None,
            seen: false,
        }
    }

    /// Create an expected warning on a specific line.
    pub fn warning_on_line(line: u32, msg: &str) -> Self {
        Self {
            severity: DiagSeverity::Warning,
            file: None,
            line,
            column: 0,
            message_contains: Some(msg.to_string()),
            message_exact: None,
            seen: false,
        }
    }

    /// Create an expected error with exact message.
    pub fn error_exact(line: u32, msg: &str) -> Self {
        Self {
            severity: DiagSeverity::Error,
            file: None,
            line,
            column: 0,
            message_contains: None,
            message_exact: Some(msg.to_string()),
            seen: false,
        }
    }

    /// Check if this expected diagnostic matches a received one.
    pub fn matches(&self, received: &ReceivedDiagnostic) -> bool {
        if self.severity != received.severity {
            return false;
        }
        if let Some(ref file) = self.file {
            if received.file.as_deref() != Some(file.as_str()) {
                return false;
            }
        }
        if self.line != 0 && self.line != received.line {
            return false;
        }
        if self.column != 0 && self.column != received.column {
            return false;
        }
        if let Some(ref contains) = self.message_contains {
            if !received.message.contains(contains.as_str()) {
                return false;
            }
        }
        if let Some(ref exact) = self.message_exact {
            if received.message != *exact {
                return false;
            }
        }
        true
    }
}

/// A diagnostic that was actually received.
#[derive(Debug, Clone)]
pub struct ReceivedDiagnostic {
    /// The severity of the diagnostic.
    pub severity: DiagSeverity,
    /// The file where the diagnostic occurred.
    pub file: Option<String>,
    /// The line number.
    pub line: u32,
    /// The column.
    pub column: u32,
    /// The diagnostic message.
    pub message: String,
    /// The diagnostic ID.
    pub diag_id: DiagID,
    /// Fix-it hints if any.
    pub fixits: Vec<String>,
}

impl VerifyDiagnosticConsumer {
    /// Create a new verify diagnostic consumer.
    pub fn new(expected: Vec<ExpectedDiagnostic>) -> Self {
        Self {
            expected,
            received: Vec::new(),
            strict: true,
            optional: Vec::new(),
        }
    }

    /// Create a lenient consumer that allows unexpected diagnostics.
    pub fn lenient(expected: Vec<ExpectedDiagnostic>) -> Self {
        Self {
            expected,
            received: Vec::new(),
            strict: false,
            optional: Vec::new(),
        }
    }

    /// Add an optional expected diagnostic.
    pub fn add_optional(&mut self, diag: ExpectedDiagnostic) {
        self.optional.push(diag);
    }

    /// Record a received diagnostic.
    pub fn record(
        &mut self,
        severity: DiagSeverity,
        file: Option<&str>,
        line: u32,
        column: u32,
        message: &str,
        diag_id: DiagID,
    ) {
        let received = ReceivedDiagnostic {
            severity,
            file: file.map(|s| s.to_string()),
            line,
            column,
            message: message.to_string(),
            diag_id,
            fixits: Vec::new(),
        };
        self.received.push(received);
    }

    /// Verify that all expected diagnostics were seen.
    /// Returns a list of missing diagnostics.
    pub fn verify(&self) -> Vec<ExpectedDiagnostic> {
        let mut missing = Vec::new();

        for expected in &self.expected {
            let found = self
                .received
                .iter()
                .any(|received| expected.matches(received));
            if !found {
                missing.push(expected.clone());
            }
        }

        missing
    }

    /// Verify and check for unexpected diagnostics (strict mode).
    /// Returns (missing, unexpected) diagnostics.
    pub fn verify_strict(&self) -> (Vec<ExpectedDiagnostic>, Vec<ReceivedDiagnostic>) {
        let missing = self.verify();

        let mut unexpected = Vec::new();
        for received in &self.received {
            let is_expected = self
                .expected
                .iter()
                .any(|expected| expected.matches(received));
            let is_optional = self.optional.iter().any(|opt| opt.matches(received));
            if !is_expected && !is_optional {
                unexpected.push(received.clone());
            }
        }

        (missing, unexpected)
    }

    /// Check if all expected diagnostics were seen (returns true if all matched).
    pub fn all_seen(&self) -> bool {
        self.verify().is_empty()
    }

    /// Get the count of received diagnostics.
    pub fn count_received(&self) -> usize {
        self.received.len()
    }

    /// Get the count of expected diagnostics.
    pub fn count_expected(&self) -> usize {
        self.expected.len()
    }

    /// Clear all received diagnostics.
    pub fn clear(&mut self) {
        self.received.clear();
    }

    /// Format the verification results as a human-readable string.
    pub fn format_results(&self) -> String {
        let mut out = String::new();
        let (missing, unexpected) = self.verify_strict();

        if missing.is_empty() && unexpected.is_empty() {
            out.push_str("All expected diagnostics received.\n");
        } else {
            if !missing.is_empty() {
                out.push_str(&format!(
                    "Missing {} expected diagnostics:\n",
                    missing.len()
                ));
                for m in &missing {
                    out.push_str(&format!(
                        "  - {:?} at line {}, contains: {:?}\n",
                        m.severity, m.line, m.message_contains
                    ));
                }
            }
            if self.strict && !unexpected.is_empty() {
                out.push_str(&format!("Unexpected {} diagnostics:\n", unexpected.len()));
                for u in &unexpected {
                    out.push_str(&format!(
                        "  - {:?} at {}:{}: {}\n",
                        u.severity,
                        u.file.as_deref().unwrap_or("<unknown>"),
                        u.line,
                        u.message
                    ));
                }
            }
        }
        out
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// CompilationPhase — tracking individual compilation phases
// ═══════════════════════════════════════════════════════════════════════════════

/// Represents a single phase of compilation with timing and error tracking.
#[derive(Debug, Clone)]
pub enum CompilationPhase {
    /// Lexing phase.
    Lexing,
    /// Preprocessing phase.
    Preprocessing,
    /// Parsing phase.
    Parsing,
    /// Semantic analysis phase.
    SemanticAnalysis,
    /// Code generation phase.
    CodeGeneration,
    /// Optimization phase.
    Optimization,
    /// Emission phase (object code, assembly, bitcode).
    Emission,
    /// Linking phase.
    Linking,
}

impl CompilationPhase {
    /// Get the name of this phase.
    pub fn name(&self) -> &'static str {
        match self {
            CompilationPhase::Lexing => "lexing",
            CompilationPhase::Preprocessing => "preprocessing",
            CompilationPhase::Parsing => "parsing",
            CompilationPhase::SemanticAnalysis => "semantic analysis",
            CompilationPhase::CodeGeneration => "code generation",
            CompilationPhase::Optimization => "optimization",
            CompilationPhase::Emission => "emission",
            CompilationPhase::Linking => "linking",
        }
    }

    /// Whether this phase must run for syntax-only mode.
    pub fn required_for_syntax_only(&self) -> bool {
        matches!(
            self,
            CompilationPhase::Lexing
                | CompilationPhase::Preprocessing
                | CompilationPhase::Parsing
                | CompilationPhase::SemanticAnalysis
        )
    }

    /// Whether this phase can be skipped with -fsyntax-only.
    pub fn can_skip(&self) -> bool {
        matches!(
            self,
            CompilationPhase::CodeGeneration
                | CompilationPhase::Optimization
                | CompilationPhase::Emission
                | CompilationPhase::Linking
        )
    }
}

/// Error tracker for a compilation pipeline.
#[derive(Debug, Clone)]
pub struct ErrorTracker {
    /// Error messages collected.
    pub errors: Vec<String>,
    /// Warning messages collected.
    pub warnings: Vec<String>,
    /// Notes collected.
    pub notes: Vec<String>,
    /// Maximum errors before aborting.
    pub error_limit: usize,
    /// Maximum warnings before suppressing.
    pub warning_limit: usize,
    /// Whether errors have reached the limit.
    pub limit_reached: bool,
}

impl ErrorTracker {
    /// Create a new error tracker.
    pub fn new() -> Self {
        Self {
            errors: Vec::new(),
            warnings: Vec::new(),
            notes: Vec::new(),
            error_limit: 20,
            warning_limit: 100,
            limit_reached: false,
        }
    }

    /// Record an error.
    pub fn error(&mut self, msg: &str) {
        if self.limit_reached {
            return;
        }
        self.errors.push(msg.to_string());
        if self.errors.len() >= self.error_limit {
            self.limit_reached = true;
        }
    }

    /// Record a warning.
    pub fn warning(&mut self, msg: &str) {
        self.warnings.push(msg.to_string());
    }

    /// Record a note.
    pub fn note(&mut self, msg: &str) {
        self.notes.push(msg.to_string());
    }

    /// Check if any errors have been recorded.
    pub fn has_errors(&self) -> bool {
        !self.errors.is_empty()
    }

    /// Get the error count.
    pub fn error_count(&self) -> usize {
        self.errors.len()
    }

    /// Get the warning count.
    pub fn warning_count(&self) -> usize {
        self.warnings.len()
    }

    /// Clear all tracked diagnostics.
    pub fn clear(&mut self) {
        self.errors.clear();
        self.warnings.clear();
        self.notes.clear();
        self.limit_reached = false;
    }

    /// Merge diagnostics from another tracker.
    pub fn merge(&mut self, other: &ErrorTracker) {
        for e in &other.errors {
            self.error(e);
        }
        for w in &other.warnings {
            self.warning(w);
        }
        for n in &other.notes {
            self.note(n);
        }
    }
}

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

/// Phase timer for measuring compilation performance.
#[derive(Debug, Clone)]
pub struct PhaseTimer {
    /// Start time for the current phase.
    start_time: Option<std::time::Instant>,
    /// Accumulated time per phase.
    pub phase_times: Vec<(CompilationPhase, std::time::Duration)>,
}

impl PhaseTimer {
    /// Create a new phase timer.
    pub fn new() -> Self {
        Self {
            start_time: None,
            phase_times: Vec::new(),
        }
    }

    /// Start timing a new phase.
    pub fn start_phase(&mut self, _phase: CompilationPhase) {
        self.start_time = Some(std::time::Instant::now());
    }

    /// End the current phase and record its duration.
    pub fn end_phase(&mut self, phase: CompilationPhase) {
        if let Some(start) = self.start_time {
            let elapsed = start.elapsed();
            self.phase_times.push((phase, elapsed));
        }
        self.start_time = None;
    }

    /// Get the total elapsed time across all phases.
    pub fn total_time(&self) -> std::time::Duration {
        self.phase_times.iter().map(|(_, d)| *d).sum()
    }

    /// Format the phase times as a human-readable string.
    pub fn format(&self) -> String {
        let mut out = String::new();
        out.push_str("=== Phase Timings ===\n");
        for (phase, duration) in &self.phase_times {
            out.push_str(&format!(
                "  {:20}: {:>8.2} ms\n",
                phase.name(),
                duration.as_secs_f64() * 1000.0
            ));
        }
        out.push_str(&format!(
            "  {:20}: {:>8.2} ms\n",
            "TOTAL",
            self.total_time().as_secs_f64() * 1000.0
        ));
        out
    }
}

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

/// Compilation unit information.
#[derive(Debug, Clone)]
pub struct CompilationUnitInfo {
    /// The source file path.
    pub source_file: PathBuf,
    /// The language standard.
    pub standard: CLangStandard,
    /// Whether this is a C++ compilation unit.
    pub is_cxx: bool,
    /// The target triple.
    pub target_triple: String,
    /// Optimization level.
    pub opt_level: OptLevel,
    /// Module name.
    pub module_name: String,
    /// Source hash for caching.
    pub source_hash: Option<u64>,
}

impl CompilationUnitInfo {
    /// Create new compilation unit info.
    pub fn new(source: &Path, standard: CLangStandard, triple: &str) -> Self {
        let module_name = source
            .file_stem()
            .and_then(|s| s.to_str())
            .unwrap_or("input")
            .to_string();

        Self {
            source_file: source.to_path_buf(),
            standard,
            is_cxx: false,
            target_triple: triple.to_string(),
            opt_level: OptLevel::O0,
            module_name,
            source_hash: None,
        }
    }

    /// Set optimization level.
    pub fn with_opt_level(mut self, level: OptLevel) -> Self {
        self.opt_level = level;
        self
    }

    /// Set as C++ compilation unit.
    pub fn with_cxx(mut self, cxx: bool) -> Self {
        self.is_cxx = cxx;
        self
    }

    /// Compute and set source hash.
    pub fn compute_hash(&mut self, source: &str) {
        // Simple hash using byte accumulation.
        let mut hash: u64 = 5381;
        for b in source.bytes() {
            hash = hash.wrapping_mul(33).wrapping_add(b as u64);
        }
        self.source_hash = Some(hash);
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// Pipeline result — unified compilation result type
// ═══════════════════════════════════════════════════════════════════════════════

/// Unified result of running a compilation pipeline.
#[derive(Debug)]
pub struct PipelineResult {
    /// Whether the pipeline completed successfully.
    pub success: bool,
    /// The output format produced.
    pub output_format: OutputFormat,
    /// The text output (assembly, IR, preprocessed).
    pub text_output: Option<String>,
    /// The binary output (object, bitcode, executable).
    pub binary_output: Option<Vec<u8>>,
    /// The produced module (if any).
    pub module: Option<Module>,
    /// Error tracker with diagnostics.
    pub error_tracker: ErrorTracker,
    /// Phase timer with performance data.
    pub phase_timer: PhaseTimer,
    /// The output file path.
    pub output_file: Option<PathBuf>,
}

impl PipelineResult {
    /// Create a successful result.
    pub fn success(format: OutputFormat) -> Self {
        Self {
            success: true,
            output_format: format,
            text_output: None,
            binary_output: None,
            module: None,
            error_tracker: ErrorTracker::new(),
            phase_timer: PhaseTimer::new(),
            output_file: None,
        }
    }

    /// Create a failed result.
    pub fn failure(format: OutputFormat, errors: Vec<String>) -> Self {
        let mut tracker = ErrorTracker::new();
        for e in &errors {
            tracker.error(e);
        }
        Self {
            success: false,
            output_format: format,
            text_output: None,
            binary_output: None,
            module: None,
            error_tracker: tracker,
            phase_timer: PhaseTimer::new(),
            output_file: None,
        }
    }

    /// Set the text output.
    pub fn with_text(mut self, text: String) -> Self {
        self.text_output = Some(text);
        self
    }

    /// Set the binary output.
    pub fn with_binary(mut self, bytes: Vec<u8>) -> Self {
        self.binary_output = Some(bytes);
        self
    }

    /// Set the module.
    pub fn with_module(mut self, module: Module) -> Self {
        self.module = Some(module);
        self
    }

    /// Set the output file.
    pub fn with_output_file(mut self, path: PathBuf) -> Self {
        self.output_file = Some(path);
        self
    }

    /// Check if there are errors.
    pub fn has_errors(&self) -> bool {
        self.error_tracker.has_errors()
    }

    /// Get the error count.
    pub fn error_count(&self) -> usize {
        self.error_tracker.error_count()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// TargetMachineStub — stub for LLVM's TargetMachine
// ═══════════════════════════════════════════════════════════════════════════════

/// Stub representing an LLVM TargetMachine for code emission.
#[derive(Debug, Clone)]
pub struct TargetMachineStub {
    /// The target triple.
    pub triple: String,
    /// The target CPU name.
    pub cpu: String,
    /// Target features string.
    pub features: String,
    /// Optimization level.
    pub opt_level: OptLevel,
    /// Code model.
    pub code_model: CodeModel,
    /// Relocation model.
    pub reloc_model: RelocModel,
    /// Whether to emit debug information.
    pub debug_info: bool,
}

/// Code model for target machine.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CodeModel {
    Default,
    Small,
    Kernel,
    Medium,
    Large,
}

/// Relocation model for target machine.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RelocModel {
    Default,
    Static,
    PIC,
    DynamicNoPic,
    ROPI,
    RWPI,
    ROPI_RWPI,
}

impl TargetMachineStub {
    /// Create a default target machine for the given triple.
    pub fn new(triple: &str) -> Self {
        Self {
            triple: triple.to_string(),
            cpu: "generic".to_string(),
            features: String::new(),
            opt_level: OptLevel::O0,
            code_model: CodeModel::Default,
            reloc_model: RelocModel::Default,
            debug_info: false,
        }
    }

    /// Set CPU name.
    pub fn with_cpu(mut self, cpu: &str) -> Self {
        self.cpu = cpu.to_string();
        self
    }

    /// Set target features.
    pub fn with_features(mut self, features: &str) -> Self {
        self.features = features.to_string();
        self
    }

    /// Set optimization level.
    pub fn with_opt_level(mut self, level: OptLevel) -> Self {
        self.opt_level = level;
        self
    }

    /// Set code model.
    pub fn with_code_model(mut self, model: CodeModel) -> Self {
        self.code_model = model;
        self
    }

    /// Set relocation model.
    pub fn with_reloc_model(mut self, model: RelocModel) -> Self {
        self.reloc_model = model;
        self
    }

    /// Enable debug info.
    pub fn with_debug_info(mut self, debug: bool) -> Self {
        self.debug_info = debug;
        self
    }

    /// Check if this is a PIC target.
    pub fn is_pic(&self) -> bool {
        matches!(
            self.reloc_model,
            RelocModel::PIC | RelocModel::ROPI | RelocModel::ROPI_RWPI
        )
    }

    /// Check if this target supports the given feature.
    pub fn has_feature(&self, feature: &str) -> bool {
        self.features.contains(feature)
    }

    /// Emit object code for the given module.
    pub fn emit_object(&self, _module: &Module) -> Result<Vec<u8>, String> {
        // In a real implementation, this would:
        // 1. Run the instruction selection pass
        // 2. Run register allocation
        // 3. Emit machine code via the MC layer
        //
        // For now, return a placeholder ELF header.
        let mut obj = Vec::new();
        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 self.triple.contains("x86_64") {
            obj.extend_from_slice(&[0x3e, 0]);
        } 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]);
        Ok(obj)
    }

    /// Emit assembly code for the given module.
    pub fn emit_assembly(&self, _module: &Module) -> Result<String, String> {
        let mut asm = String::new();
        asm.push_str(&format!("\t.arch {}\n", self.triple));
        asm.push_str(&format!("\t.cpu {}\n", self.cpu));
        asm.push_str("\t.text\n");
        Ok(asm)
    }
}

impl Default for TargetMachineStub {
    fn default() -> Self {
        Self::new("x86_64-unknown-linux-gnu")
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// ModuleVerifier — verify LLVM module correctness
// ═══════════════════════════════════════════════════════════════════════════════

/// A verifier that checks LLVM module correctness after code generation.
#[derive(Debug, Clone)]
pub struct ModuleVerifier {
    /// Whether to abort on first error.
    pub abort_on_error: bool,
    /// Whether to print verbose output.
    pub verbose: bool,
    /// Collected verification errors.
    pub errors: Vec<String>,
}

impl ModuleVerifier {
    /// Create a new module verifier.
    pub fn new() -> Self {
        Self {
            abort_on_error: false,
            verbose: false,
            errors: Vec::new(),
        }
    }

    /// Verify a module for correctness.
    pub fn verify(&mut self, module: &Module) -> bool {
        self.errors.clear();

        // Check that every function has at least one basic block.
        for func in &module.functions {
            let func = func.borrow();
            if func.blocks.is_empty() {
                self.errors
                    .push(format!("function '{}' has no basic blocks", func.name));
                if self.abort_on_error {
                    return false;
                }
            }

            // Check that each basic block's terminator is valid.
            for bb in &func.blocks {
                let bb = bb.borrow();
                if bb.instructions.is_empty() && !bb.name.is_empty() {
                    if self.verbose {
                        // Empty blocks are okay in some cases.
                    }
                }
                // Verify the block's terminator is last.
                if let Some(last) = bb.instructions.last() {
                    let last = last.borrow();
                    if !self.is_valid_terminator(&last.opcode) {
                        self.errors.push(format!(
                            "block '{}' in function '{}' does not end with a terminator instruction",
                            bb.name, func.name
                        ));
                        if self.abort_on_error {
                            return false;
                        }
                    }
                }
            }
        }

        // Check global initializers.
        for gv in &module.globals {
            let gv = gv.borrow();
            if gv.initializer.is_none() && gv.is_constant {
                self.errors.push(format!(
                    "constant global '{}' must have an initializer",
                    gv.name
                ));
                if self.abort_on_error {
                    return false;
                }
            }
        }

        self.errors.is_empty()
    }

    /// Check if an opcode is a valid terminator instruction.
    fn is_valid_terminator(&self, opcode: &Option<Opcode>) -> bool {
        if let Some(op) = opcode {
            matches!(
                op,
                Opcode::Ret
                    | Opcode::Br
                    | Opcode::Switch
                    | Opcode::IndirectBr
                    | Opcode::Invoke
                    | Opcode::Resume
                    | Opcode::Unreachable
                    | Opcode::CatchRet
                    | Opcode::CatchSwitch
            )
        } else {
            false
        }
    }

    /// Verify a single function.
    pub fn verify_function(&mut self, func: &Function) -> bool {
        self.errors.clear();

        if func.basic_blocks.is_empty() {
            self.errors.push(format!(
                "function '{}' has no body",
                func.value.borrow().name
            ));
            return false;
        }

        // Check that the entry block is first.
        if let Some(entry) = func.basic_blocks.first() {
            if entry.borrow().name != "entry"
                && !func.basic_blocks.iter().any(|b| b.borrow().name == "entry")
            {
                if self.verbose {
                    // Entry block doesn't have to be named "entry".
                }
            }
        }

        true
    }

    /// Get the verification errors.
    pub fn get_errors(&self) -> &[String] {
        &self.errors
    }

    /// Check if the module passed verification.
    pub fn passed(&self) -> bool {
        self.errors.is_empty()
    }
}

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

// ═══════════════════════════════════════════════════════════════════════════════
// OptimizerConfig — optimization pass configuration
// ═══════════════════════════════════════════════════════════════════════════════

/// Configuration for running optimization passes on an LLVM module.
#[derive(Debug, Clone)]
pub struct OptimizerConfig {
    /// Optimization level.
    pub opt_level: OptLevel,
    /// Enable inlining.
    pub inline: bool,
    /// Inline threshold.
    pub inline_threshold: u32,
    /// Enable loop unrolling.
    pub loop_unroll: bool,
    /// Enable vectorization.
    pub vectorize: bool,
    /// Enable slp vectorization.
    pub slp_vectorize: bool,
    /// Enable global value numbering.
    pub gvn: bool,
    /// Enable dead code elimination.
    pub dce: bool,
    /// Enable constant propagation.
    pub const_prop: bool,
    /// Enable tail call elimination.
    pub tail_call_elim: bool,
    /// Enable function merging.
    pub merge_functions: bool,
    /// Additional custom passes.
    pub custom_passes: Vec<String>,
}

impl OptimizerConfig {
    /// Create default config for O0.
    pub fn o0() -> Self {
        Self {
            opt_level: OptLevel::O0,
            inline: false,
            inline_threshold: 0,
            loop_unroll: false,
            vectorize: false,
            slp_vectorize: false,
            gvn: false,
            dce: false,
            const_prop: false,
            tail_call_elim: false,
            merge_functions: false,
            custom_passes: Vec::new(),
        }
    }

    /// Create default config for O1.
    pub fn o1() -> Self {
        Self {
            opt_level: OptLevel::O1,
            inline: true,
            inline_threshold: 225,
            loop_unroll: false,
            vectorize: false,
            slp_vectorize: false,
            gvn: true,
            dce: true,
            const_prop: true,
            tail_call_elim: true,
            merge_functions: false,
            custom_passes: Vec::new(),
        }
    }

    /// Create default config for O2.
    pub fn o2() -> Self {
        Self {
            opt_level: OptLevel::O2,
            inline: true,
            inline_threshold: 275,
            loop_unroll: true,
            vectorize: true,
            slp_vectorize: true,
            gvn: true,
            dce: true,
            const_prop: true,
            tail_call_elim: true,
            merge_functions: true,
            custom_passes: Vec::new(),
        }
    }

    /// Create default config for O3.
    pub fn o3() -> Self {
        Self {
            opt_level: OptLevel::O3,
            inline: true,
            inline_threshold: 350,
            loop_unroll: true,
            vectorize: true,
            slp_vectorize: true,
            gvn: true,
            dce: true,
            const_prop: true,
            tail_call_elim: true,
            merge_functions: true,
            custom_passes: Vec::new(),
        }
    }

    /// Create default config for Os (size optimization).
    pub fn os() -> Self {
        Self {
            opt_level: OptLevel::Os,
            inline: true,
            inline_threshold: 75,
            loop_unroll: false,
            vectorize: false,
            slp_vectorize: false,
            gvn: false,
            dce: true,
            const_prop: true,
            tail_call_elim: true,
            merge_functions: true,
            custom_passes: Vec::new(),
        }
    }

    /// Create config from an optimization level.
    pub fn from_opt_level(level: OptLevel) -> Self {
        match level {
            OptLevel::O0 => Self::o0(),
            OptLevel::O1 => Self::o1(),
            OptLevel::O2 => Self::o2(),
            OptLevel::O3 => Self::o3(),
            OptLevel::Os => Self::os(),
            OptLevel::Oz => {
                let mut s = Self::os();
                s.opt_level = OptLevel::Oz;
                s.inline_threshold = 25;
                s
            }
        }
    }

    /// Add a custom pass.
    pub fn add_pass(&mut self, pass_name: &str) {
        self.custom_passes.push(pass_name.to_string());
    }

    /// Check if any optimizations are enabled.
    pub fn is_optimizing(&self) -> bool {
        self.opt_level.is_optimizing()
    }

    /// Get a human-readable description.
    pub fn description(&self) -> String {
        let mut desc = format!("Optimization level: {:?}", self.opt_level);
        if self.inline {
            desc.push_str(&format!(", inline(threshold={})", self.inline_threshold));
        }
        if self.loop_unroll {
            desc.push_str(", loop-unroll");
        }
        if self.vectorize {
            desc.push_str(", vectorize");
        }
        if self.slp_vectorize {
            desc.push_str(", slp-vectorize");
        }
        desc
    }
}

impl Default for OptimizerConfig {
    fn default() -> Self {
        Self::o0()
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// Emitter — common emission interface for all output formats
// ═══════════════════════════════════════════════════════════════════════════════

/// Common interface for code emission in all output formats.
#[derive(Debug)]
pub struct CodeEmitter {
    /// The target machine configuration.
    pub target_machine: TargetMachineStub,
    /// The optimizer configuration.
    pub optimizer_config: OptimizerConfig,
    /// Whether to verify the module before emission.
    pub verify_module: bool,
    /// Whether to include debug info.
    pub include_debug_info: bool,
    /// Debug info kind.
    pub debug_info_kind: DebugInfoKind,
}

impl CodeEmitter {
    /// Create a new code emitter.
    pub fn new(target: TargetMachineStub, opt: OptimizerConfig) -> Self {
        Self {
            target_machine: target,
            optimizer_config: opt,
            verify_module: true,
            include_debug_info: false,
            debug_info_kind: DebugInfoKind::None,
        }
    }

    /// Emit object code from a module.
    pub fn emit_object(&self, module: &Module) -> Result<Vec<u8>, String> {
        // Verify if requested.
        if self.verify_module {
            let mut verifier = ModuleVerifier::new();
            if !verifier.verify(module) {
                return Err(format!("module verification failed: {:?}", verifier.errors));
            }
        }
        self.target_machine.emit_object(module)
    }

    /// Emit assembly code from a module.
    pub fn emit_assembly(&self, module: &Module) -> Result<String, String> {
        self.target_machine.emit_assembly(module)
    }

    /// Check if debug info should be emitted.
    pub fn should_emit_debug_info(&self) -> bool {
        self.include_debug_info && self.debug_info_kind != DebugInfoKind::None
    }
}

/// Default implementation for convenience.
impl Default for CodeEmitter {
    fn default() -> Self {
        Self::new(TargetMachineStub::default(), OptimizerConfig::default())
    }
}

/// A convenience type alias for the full compilation pipeline function type.
pub type CompilationPipelineFn = fn(source: &str, triple: &str) -> Result<Vec<u8>, Vec<String>>;

/// A convenience type for the IR generation pipeline function type.
pub type IRPipelineFn = fn(source: &str, triple: &str) -> Result<String, Vec<String>>;

/// Pipeline registry for dynamic dispatch of compilation strategies.
#[derive(Debug, Clone)]
pub struct PipelineRegistry {
    pub default_pipeline: String,
    pub pipelines: std::collections::HashMap<String, CompilationPipelineFn>,
}

impl PipelineRegistry {
    pub fn new() -> Self {
        let mut registry = Self {
            default_pipeline: "standard".to_string(),
            pipelines: std::collections::HashMap::new(),
        };
        registry.pipelines.insert(
            "standard".to_string(),
            compile_to_object as CompilationPipelineFn,
        );
        registry
    }

    pub fn register(&mut self, name: &str, pipeline: CompilationPipelineFn) {
        self.pipelines.insert(name.to_string(), pipeline);
    }

    pub fn run(&self, source: &str, triple: &str) -> Result<Vec<u8>, Vec<String>> {
        let pipeline = self
            .pipelines
            .get(&self.default_pipeline)
            .or_else(|| self.pipelines.values().next())
            .ok_or_else(|| vec!["no pipeline registered".to_string()])?;
        pipeline(source, triple)
    }
}

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

// ═══════════════════════════════════════════════════════════════════════════════
// Pipeline convenience functions
// ═══════════════════════════════════════════════════════════════════════════════

/// Compile a C source string to object bytes through the full pipeline.
///
/// This is a convenience function that creates a CompilerInstance, runs
/// lex→parse→sema→codegen, and returns the resulting object bytes.
pub fn compile_to_object(source: &str, triple: &str) -> Result<Vec<u8>, Vec<String>> {
    let opts = CompilerOptions {
        target_triple: triple.to_string(),
        action: FrontendActionKind::EmitObj,
        ..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 = lexer::tokenize(source, compiler.opts.standard);
    let mut parser = 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 = 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());
    }

    let mut cg = ClangCodeGen::new("input", triple);
    cg.compile(&tu).map_err(|e| {
        e.iter()
            .map(|err| format!("codegen: {}", err))
            .collect::<Vec<_>>()
    })?;

    // In a real implementation, this would go through the TargetMachine
    // to emit object bytes.  For now, return empty bytes.
    Ok(Vec::new())
}

/// Compile C source to LLVM IR text.
pub fn compile_to_ir(source: &str, triple: &str) -> Result<String, Vec<String>> {
    let opts = CompilerOptions {
        target_triple: triple.to_string(),
        emit_llvm: 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 = lexer::tokenize(source, compiler.opts.standard);
    let mut parser = 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 = Sema::new(compiler.opts.standard);
    sema.analyze(&tu).map_err(|e| {
        e.iter()
            .map(|err| format!("sema: {}", err))
            .collect::<Vec<_>>()
    })?;

    let mut cg = ClangCodeGen::new("input", triple);
    cg.compile(&tu).map_err(|e| {
        e.iter()
            .map(|err| format!("codegen: {}", err))
            .collect::<Vec<_>>()
    })?;

    // Get the module as IR text.
    // In a real impl this would serialize to .ll format.
    let ir = String::new();
    let _ = cg.module;
    Ok(ir)
}

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

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

    // ── CompilerOptions ──────────────────────────────────────────────────

    #[test]
    fn test_compiler_options_default() {
        let opts = CompilerOptions::default();
        assert_eq!(opts.standard, CLangStandard::C17);
        assert_eq!(opts.target_triple, "x86_64-unknown-linux-gnu");
        assert_eq!(opts.opt_level, OptLevel::O0);
    }

    #[test]
    fn test_compiler_options_from_clang_options() {
        let co = ClangOptions {
            standard: CLangStandard::C11,
            optimize: true,
            debug_info: true,
            warnings: true,
            pedantic: true,
            wall: true,
            werror: true,
            verbose: false,
            includes: vec!["/usr/include".to_string()],
            defines: vec![("FOO".to_string(), Some("bar".to_string()))],
            output_file: Some("out.o".to_string()),
            target_triple: "aarch64-unknown-linux-gnu".to_string(),
        };
        let opts = CompilerOptions::from_clang_options(&co);
        assert_eq!(opts.standard, CLangStandard::C11);
        assert_eq!(opts.opt_level, OptLevel::O2);
        assert!(opts.debug_info);
        assert!(opts.wall);
        assert!(opts.pedantic);
        assert!(opts.werror);
        assert_eq!(opts.includes.len(), 1);
        assert!(opts.output_file.is_some());
    }

    // ── FileManager ──────────────────────────────────────────────────────

    #[test]
    fn test_file_manager_virtual_file() {
        let mut fm = FileManager::new();
        let fid = fm.get_virtual_file("test.c", "int x;".to_string()).unwrap();
        assert!(fid.0 > 0);
        let entry = fm.get_file_by_id(fid).unwrap();
        assert_eq!(entry.name, "test.c");
        assert!(entry.is_virtual);
    }

    #[test]
    fn test_file_manager_overlay() {
        let mut fm = FileManager::new();
        fm.add_overlay("builtin.h".to_string(), "#define NULL 0".to_string());
        let fid = fm.get_file(Path::new("builtin.h")).unwrap();
        let entry = fm.get_file_by_id(fid).unwrap();
        assert!(entry.is_virtual);
    }

    #[test]
    fn test_file_manager_include_search() {
        // This test checks include path searching with a virtual overlay.
        let mut fm = FileManager::new();
        fm.add_include_path(PathBuf::from("/include"));
        fm.add_overlay(
            "/include/header.h".to_string(),
            "int answer = 42;".to_string(),
        );
        let result = fm.find_include("header.h", None);
        assert!(result.is_some());
    }

    // ── SourceManager ────────────────────────────────────────────────────

    #[test]
    fn test_source_manager_virtual_file() {
        let fm = FileManager::new();
        let mut sm = SourceManager::new(fm);
        let fid = sm
            .load_virtual_file("test.c", "int x;\nint y;\nint z;\n".to_string())
            .unwrap();
        let loc1 = sm.get_location(fid, 0);
        assert_eq!(loc1.line, 1);
        assert_eq!(loc1.column, 1);

        let loc2 = sm.get_location(fid, 7); // after "int x;\n" (7 bytes incl newline)
        assert_eq!(loc2.line, 2);
    }

    #[test]
    fn test_source_manager_get_line() {
        let fm = FileManager::new();
        let mut sm = SourceManager::new(fm);
        let fid = sm
            .load_virtual_file("test.c", "line one\nline two\n".to_string())
            .unwrap();
        let loc1 = sm.get_location(fid, 0);
        let line1 = sm.get_line(loc1).unwrap();
        assert_eq!(line1, "line one");

        let loc2 = sm.get_location(fid, 9); // after "line one\n"
        let line2 = sm.get_line(loc2).unwrap();
        assert_eq!(line2, "line two");
    }

    #[test]
    fn test_source_manager_invalid_location() {
        let fm = FileManager::new();
        let sm = SourceManager::new(fm);
        let loc = SourceLocation::invalid();
        assert!(!loc.is_valid());
        assert_eq!(loc.to_display(&sm), "<invalid loc>");
    }

    // ── CompilerInvocation ───────────────────────────────────────────────

    #[test]
    fn test_compiler_invocation_default() {
        let inv = CompilerInvocation::default();
        assert_eq!(inv.opts.standard, CLangStandard::C17);
    }

    #[test]
    fn test_compiler_invocation_parse_std() {
        let inv = CompilerInvocation::from_args(["clang", "-std=c11", "-c", "file.c"]);
        assert_eq!(inv.opts.standard, CLangStandard::C11);
        assert!(inv.opts.input_files.len() >= 1);
    }

    #[test]
    fn test_compiler_invocation_parse_optimization() {
        let inv = CompilerInvocation::from_args(["clang", "-O2", "-g", "file.c"]);
        assert_eq!(inv.opts.opt_level, OptLevel::O2);
        assert!(inv.opts.debug_info);
    }

    #[test]
    fn test_compiler_invocation_parse_emit_llvm() {
        let inv = CompilerInvocation::from_args(["clang", "-emit-llvm", "file.c"]);
        assert!(inv.opts.emit_llvm);
    }

    #[test]
    fn test_compiler_invocation_parse_includes() {
        let inv = CompilerInvocation::from_args([
            "clang",
            "-I/usr/include",
            "-I",
            "/usr/local/include",
            "file.c",
        ]);
        assert!(inv.opts.includes.len() >= 1);
    }

    #[test]
    fn test_compiler_invocation_parse_defines() {
        let inv = CompilerInvocation::from_args(["clang", "-DFOO", "-DBAR=baz", "file.c"]);
        assert!(inv.opts.defines.iter().any(|(n, _)| n == "FOO"));
        assert!(inv.opts.defines.iter().any(|(n, _)| n == "BAR"));
    }

    // ── CompilerInstance ─────────────────────────────────────────────────

    #[test]
    fn test_compiler_instance_create_default() {
        let ci = CompilerInstance::create_default();
        assert_eq!(ci.target_triple(), "x86_64-unknown-linux-gnu");
    }

    // ── Full pipeline test ───────────────────────────────────────────────

    #[test]
    fn test_full_pipeline_minimal() {
        let source = "int main(void) { return 0; }";
        let result = compile_to_object(source, "x86_64-unknown-linux-gnu");
        // Should succeed (even if object bytes are empty placeholder).
        assert!(result.is_ok());
    }

    #[test]
    fn test_full_pipeline_with_function() {
        let source = "int add(int a, int b) { return a + b; }";
        let result = compile_to_ir(source, "x86_64-unknown-linux-gnu");
        // Should succeed and produce some IR text.
        assert!(result.is_ok());
    }

    #[test]
    fn test_compiler_invocation_output_file() {
        let inv = CompilerInvocation::from_args(["clang", "-c", "hello.c", "-o", "hello.o"]);
        let out = inv.output_file();
        assert_eq!(out, PathBuf::from("hello.o"));
    }

    #[test]
    fn test_compiler_invocation_output_file_stem() {
        let inv = CompilerInvocation::from_args(["clang", "-S", "hello.c"]);
        let out = inv.output_file();
        assert_eq!(out, PathBuf::from("hello.s"));
    }

    // ── FrontendAction ───────────────────────────────────────────────────

    #[test]
    fn test_frontend_action_for_kind_preprocess() {
        let action = FrontendAction::for_kind(FrontendActionKind::PreprocessOnly);
        match action {
            FrontendAction::PreprocessOnly(_) => {}
            _ => panic!("expected PreprocessOnly"),
        }
    }

    #[test]
    fn test_frontend_action_for_kind_syntax_only() {
        let action = FrontendAction::for_kind(FrontendActionKind::SyntaxOnly);
        match action {
            FrontendAction::SyntaxOnly(_) => {}
            _ => panic!("expected SyntaxOnly"),
        }
    }

    #[test]
    fn test_frontend_action_for_kind_emit_obj() {
        let action = FrontendAction::for_kind(FrontendActionKind::EmitObj);
        match action {
            FrontendAction::EmitObj(_) => {}
            _ => panic!("expected EmitObj"),
        }
    }

    // ── CompilationDriver ────────────────────────────────────────────────

    #[test]
    fn test_compilation_driver_from_args() {
        let mut driver = CompilationDriver::from_args(["clang", "-std=c11", "-fsyntax-only", "-c"]);
        // Since we have no input files, we can't actually run full pipeline.
        // Just verify it was constructed.
        assert_eq!(driver.compiler.opts.standard, CLangStandard::C11);
    }

    // ── OptLevel ─────────────────────────────────────────────────────────

    #[test]
    fn test_opt_level_from_str() {
        assert_eq!(OptLevel::from_str("0"), Some(OptLevel::O0));
        assert_eq!(OptLevel::from_str("2"), Some(OptLevel::O2));
        assert_eq!(OptLevel::from_str("s"), Some(OptLevel::Os));
        assert_eq!(OptLevel::from_str("invalid"), None);
    }

    #[test]
    fn test_opt_level_is_optimizing() {
        assert!(!OptLevel::O0.is_optimizing());
        assert!(OptLevel::O2.is_optimizing());
        assert!(OptLevel::Os.is_optimizing());
    }

    // ── InputLanguage ────────────────────────────────────────────────────

    #[test]
    fn test_input_language_from_str() {
        assert_eq!(InputLanguage::from_str("c"), Some(InputLanguage::C));
        assert_eq!(InputLanguage::from_str("c++"), Some(InputLanguage::CXX));
        assert!(InputLanguage::from_str("fortran").is_none());
    }

    // ── MultiplexConsumer ────────────────────────────────────────────────

    #[test]
    fn test_multiplex_consumer_basic() {
        let mut mc = MultiplexConsumer::new(vec![
            Box::new(SyntaxOnlyConsumer),
            Box::new(ASTDumpConsumer),
        ]);
        mc.consumers.clear(); // verify we can access consumers
    }

    // ── AST consumers ────────────────────────────────────────────────────

    #[test]
    fn test_syntax_only_consumer() {
        let mut c = SyntaxOnlyConsumer;
        c.handle_top_level_decl(&Decl::VarDecl {
            name: "x".to_string(),
            ty: QualType::int(),
            init: None,
        });
        // No panic = success.
    }
}