ryo_executor/engine/

ast_mutation_engine.rs

//! AST Mutation Engine - Core execution without file I/O
//!
//! Executes mutations against ASTRegistry and SymbolRegistry only.
//! No PureFile or file system access during execution.

use ryo_analysis::{
    ASTRegistry, AnalysisContext, SymbolId, SymbolKind, SymbolPath, SymbolRegistry,
};
use ryo_mutations::MutationResult;
use ryo_source::pure::PureItem;

use super::ast_reg_apply::ASTRegApply;
use super::events::{ModificationType, MutationEvent};

/// Error when resolving a symbol
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ResolveError {
    /// Symbol not found (by ID or name)
    NotFound,
    /// Multiple symbols match the name - use full path to disambiguate
    /// (only occurs with name-based lookup, never with ID lookup)
    Ambiguous,
}

/// Result of mutation execution
#[derive(Debug, Clone)]
pub struct ExecutionResult {
    /// Mutation result (changes count, etc.)
    pub result: MutationResult,
    /// Events emitted during execution
    pub events: Vec<MutationEvent>,
}

impl ExecutionResult {
    /// Create a new execution result
    pub fn new(result: MutationResult, events: Vec<MutationEvent>) -> Self {
        Self { result, events }
    }

    /// Create a result indicating no changes
    pub fn no_change() -> Self {
        Self {
            result: MutationResult {
                mutation_type: String::new(),
                changes: 0,
                description: String::new(),
            },
            events: vec![],
        }
    }

    /// Check if any changes were made
    pub fn has_changes(&self) -> bool {
        self.result.changes > 0
    }
}

/// AST-centric mutation execution engine
///
/// Executes mutations against registries only, with no file I/O.
///
/// # Invariants
///
/// - NO file I/O during execution
/// - NO PureFile access (only ASTRegistry)
/// - ALL state changes via Registry APIs
///
/// # Usage
///
/// ```ignore
/// let mutation = AddFieldMutation::new("MyStruct", "new_field", "i32");
/// let result = ASTMutationEngine::execute_ast_reg(&mutation, &mut ctx);
///
/// for event in &result.events {
///     println!("{}", event);
/// }
/// ```
pub struct ASTMutationEngine;

impl ASTMutationEngine {
    /// Execute a mutation that implements ASTRegApply
    ///
    /// This is the primary execution path for registry-based mutations.
    /// Uses `ASTRegApply::apply_to_registry` for actual execution.
    ///
    /// # Type Parameters
    ///
    /// * `M` - Mutation type that implements both `Mutation` and `ASTRegApply`
    ///
    /// # Example
    ///
    /// ```ignore
    /// use ryo_executor::ASTMutationEngine;
    ///
    /// let mutation = AddFieldMutation::new("MyStruct", "field", "i32");
    /// let result = ASTMutationEngine::execute_ast_reg(&mutation, &mut ctx);
    /// ```
    pub fn execute_ast_reg<M: ASTRegApply>(
        mutation: &M,
        ctx: &mut AnalysisContext,
    ) -> ExecutionResult {
        // SAFETY: ASTMutationContext borrows `ast_registry` and `registry`
        // mutably. We need a *shared* borrow of `code_graph` for the same
        // lifetime, which the borrow checker would reject because
        // `AnalysisContext` owns all three fields. Split the borrow up front
        // by going through raw pointers, then immediately re-create safe
        // references from disjoint fields. This is sound: the three fields
        // are disjoint and the resulting references do not alias.
        let code_graph_ptr: *const ryo_analysis::CodeGraphV2 = &ctx.code_graph;
        let mut mutation_ctx = ASTMutationContext::new(&mut ctx.ast_registry, &mut ctx.registry)
            .with_code_graph(unsafe { &*code_graph_ptr });

        let result = mutation.apply_to_registry(&mut mutation_ctx);
        let events = mutation_ctx.into_events();

        ExecutionResult::new(result, events)
    }

    /// Execute multiple ASTRegApply mutations in sequence
    pub fn execute_ast_reg_batch<M: ASTRegApply>(
        mutations: &[&M],
        ctx: &mut AnalysisContext,
    ) -> ExecutionResult {
        let mut total_changes = 0;
        let mut all_events = Vec::new();

        for mutation in mutations {
            let result = Self::execute_ast_reg(*mutation, ctx);
            total_changes += result.result.changes;
            all_events.extend(result.events);
        }

        ExecutionResult::new(
            MutationResult {
                mutation_type: "ast_reg_batch".to_string(),
                changes: total_changes,
                description: format!("{} mutations executed", mutations.len()),
            },
            all_events,
        )
    }

    /// Execute a boxed ASTRegApply mutation (dynamic dispatch)
    ///
    /// This is the primary execution path for V2 conversion.
    /// Accepts `Box<dyn ASTRegApply>` from `MutationConverter::convert_v2()`.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let mutations = converter.convert_v2(&spec, &ctx)?;
    /// for mutation in mutations {
    ///     let result = ASTMutationEngine::execute_ast_reg_dyn(mutation.as_ref(), &mut ctx);
    /// }
    /// ```
    pub fn execute_ast_reg_dyn(
        mutation: &dyn ASTRegApply,
        ctx: &mut AnalysisContext,
    ) -> ExecutionResult {
        // SAFETY: ASTMutationContext borrows `ast_registry` and `registry`
        // mutably. We need a *shared* borrow of `code_graph` for the same
        // lifetime, which the borrow checker would reject because
        // `AnalysisContext` owns all three fields. Split the borrow up front
        // by going through raw pointers, then immediately re-create safe
        // references from disjoint fields. This is sound: the three fields
        // are disjoint and the resulting references do not alias.
        let code_graph_ptr: *const ryo_analysis::CodeGraphV2 = &ctx.code_graph;
        let mut mutation_ctx = ASTMutationContext::new(&mut ctx.ast_registry, &mut ctx.registry)
            .with_code_graph(unsafe { &*code_graph_ptr });

        let result = mutation.apply_to_registry(&mut mutation_ctx);
        let events = mutation_ctx.into_events();

        ExecutionResult::new(result, events)
    }

    /// Execute multiple boxed ASTRegApply mutations in sequence (dynamic dispatch)
    ///
    /// This is the batch execution path for V2 conversion.
    /// Accepts `Vec<Box<dyn ASTRegApply>>` from `MutationConverter::convert_v2()`.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let mutations = converter.convert_v2(&spec, &ctx)?;
    /// let result = ASTMutationEngine::execute_ast_reg_batch_dyn(mutations, &mut ctx);
    /// ```
    pub fn execute_ast_reg_batch_dyn(
        mutations: Vec<Box<dyn ASTRegApply>>,
        ctx: &mut AnalysisContext,
    ) -> ExecutionResult {
        let mutation_count = mutations.len();
        let mut total_changes = 0;
        let mut all_events = Vec::new();

        for mutation in mutations {
            let result = Self::execute_ast_reg_dyn(mutation.as_ref(), ctx);
            total_changes += result.result.changes;
            all_events.extend(result.events);
        }

        ExecutionResult::new(
            MutationResult {
                mutation_type: "ast_reg_batch_v2".to_string(),
                changes: total_changes,
                description: format!("{} V2 mutations executed", mutation_count),
            },
            all_events,
        )
    }
}

/// Context passed to `ASTRegApply::apply_to_registry`
///
/// Provides access to ASTRegistry, SymbolRegistry, and event emission.
///
/// # Binary Entry (main.rs) Support
///
/// Binary entry symbols (main.rs, src/bin/*.rs) are registered in the unified
/// `items` map like library symbols. Use `WorkspaceFilePath::is_binary_entry()`
/// to identify binary files when needed for file output.
pub struct ASTMutationContext<'a> {
    /// AST storage (complete PureItem per symbol)
    pub ast_registry: &'a mut ASTRegistry,
    /// Symbol metadata (path ↔ id, kind, span, etc.)
    pub symbol_registry: &'a mut SymbolRegistry,
    /// Optional read-only handle to the analysis CodeGraphV2. Mutations
    /// that need to discover relationships beyond the (`ast`, `symbol`)
    /// pair — most notably `ExtractTraitMutation`, which has to inject a
    /// `use Trait;` into every file that calls one of the methods it just
    /// moved into a trait — receive the graph through this field.
    ///
    /// Held as an `Option<&'a CodeGraphV2>` so legacy callers that
    /// construct an `ASTMutationContext` without a graph keep working
    /// (the field is `None` and graph-dependent steps gracefully skip).
    pub code_graph: Option<&'a ryo_analysis::CodeGraphV2>,
    /// Events collected during execution
    events: Vec<MutationEvent>,
}

impl<'a> ASTMutationContext<'a> {
    /// Create a new mutation context (without a CodeGraphV2 handle).
    pub fn new(ast_registry: &'a mut ASTRegistry, symbol_registry: &'a mut SymbolRegistry) -> Self {
        Self {
            ast_registry,
            symbol_registry,
            code_graph: None,
            events: Vec::new(),
        }
    }

    /// Attach a read-only `CodeGraphV2` handle to the context. Required by
    /// mutations (e.g. `ExtractTraitMutation`) that need to walk caller
    /// relationships to update call sites at apply-time.
    pub fn with_code_graph(mut self, graph: &'a ryo_analysis::CodeGraphV2) -> Self {
        self.code_graph = Some(graph);
        self
    }

    /// Consume context and return collected events
    pub fn into_events(self) -> Vec<MutationEvent> {
        self.events
    }

    // ========================================================================
    // Event emission
    // ========================================================================

    /// Emit an event (for logging/tracking)
    pub fn emit(&mut self, event: MutationEvent) {
        self.events.push(event);
    }

    /// Emit symbol added event
    pub fn emit_added(&mut self, path: SymbolPath, kind: SymbolKind) {
        self.emit(MutationEvent::SymbolAdded { path, kind });
    }

    /// Emit symbol removed event
    pub fn emit_removed(&mut self, path: SymbolPath) {
        self.emit(MutationEvent::SymbolRemoved { path });
    }

    /// Emit symbol modified event
    pub fn emit_modified(&mut self, id: SymbolId, modification: ModificationType) {
        // CRITICAL FIX: Sync Impl blocks to module_items
        // ImplBlocks are stored in both `items` (for direct access via get_mut)
        // and `module_items` (for file generation). When get_mut modifies an Impl,
        // we must sync the changes to module_items.
        let item_clone = self.ast_registry.get(id).cloned();
        if let Some(item) = item_clone {
            if matches!(item, ryo_source::pure::PureItem::Impl(_)) {
                // Find parent module
                if let Some(path) = self.symbol_registry.path(id) {
                    if let Some(parent_path) = path.parent() {
                        if let Some(parent_id) = self.symbol_registry.lookup(&parent_path) {
                            // Get or create module_items
                            if let Some(module_items) =
                                self.ast_registry.get_module_items_mut(parent_id)
                            {
                                // Find and replace the Impl block in module_items
                                if let Some(pos) = module_items.iter().position(|i| {
                                    if let ryo_source::pure::PureItem::Impl(impl_block) = i {
                                        if let ryo_source::pure::PureItem::Impl(ref modified_impl) =
                                            item
                                        {
                                            impl_block.self_ty == modified_impl.self_ty
                                                && impl_block.trait_ == modified_impl.trait_
                                        } else {
                                            false
                                        }
                                    } else {
                                        false
                                    }
                                }) {
                                    module_items[pos] = item;
                                }
                            }
                        }
                    }
                }
            }
        }

        self.emit(MutationEvent::SymbolModified { id, modification });
    }

    /// Emit symbol renamed event
    pub fn emit_renamed(&mut self, old_path: SymbolPath, new_path: SymbolPath) {
        self.emit(MutationEvent::SymbolRenamed {
            old_path,
            new_path: Box::new(new_path),
        });
    }

    // ========================================================================
    // AST access
    // ========================================================================

    /// Get AST for a symbol (immutable)
    pub fn get_ast(&self, id: SymbolId) -> Option<&PureItem> {
        self.ast_registry.get(id)
    }

    /// Get AST for a symbol (mutable)
    pub fn get_ast_mut(&mut self, id: SymbolId) -> Option<&mut PureItem> {
        self.ast_registry.get_mut(id)
    }

    /// Set AST for a symbol
    pub fn set_ast(&mut self, id: SymbolId, item: PureItem) {
        self.ast_registry.set(id, item);
    }

    /// Check if symbol has AST
    pub fn has_ast(&self, id: SymbolId) -> bool {
        self.ast_registry.contains(id)
    }

    // ========================================================================
    // Symbol lookup
    // ========================================================================

    /// Lookup symbol by path
    pub fn lookup(&self, path: &SymbolPath) -> Option<SymbolId> {
        self.symbol_registry.lookup(path)
    }

    /// Get symbol path by ID
    pub fn path(&self, id: SymbolId) -> Option<&SymbolPath> {
        self.symbol_registry.path(id)
    }

    /// Get symbol kind by ID
    pub fn kind(&self, id: SymbolId) -> Option<SymbolKind> {
        self.symbol_registry.kind(id)
    }

    /// Resolve symbol ID by name, supporting both simple name and full path.
    ///
    /// - If `name` contains "::", performs full path match (always unique)
    /// - Otherwise, matches by last segment (symbol name) only
    ///
    /// # Errors
    /// - `ResolveError::NotFound` - no matching symbol
    /// - `ResolveError::Ambiguous` - multiple symbols match (use full path)
    ///
    /// # Example
    /// ```ignore
    /// // Find struct by simple name (fails if multiple "User" exist)
    /// let id = ctx.resolve_symbol_by_name("User", &[SymbolKind::Struct])?;
    ///
    /// // Find by full path (always unambiguous)
    /// let id = ctx.resolve_symbol_by_name("crate::user::UserStatus", &[SymbolKind::Enum])?;
    /// ```
    pub fn resolve_symbol_by_name(
        &self,
        name: &str,
        kinds: &[SymbolKind],
    ) -> Result<SymbolId, ResolveError> {
        let mut found: Option<SymbolId> = None;

        for (id, path) in self.symbol_registry.iter() {
            // Check kind matches
            let kind_matches = self
                .symbol_registry
                .kind(id)
                .map(|k| kinds.contains(&k))
                .unwrap_or(false);
            if !kind_matches {
                continue;
            }

            // Check name matches
            let name_matches = if name.contains("::") {
                path.to_string() == name
            } else {
                path.name() == name
            };
            if !name_matches {
                continue;
            }

            // Found a match
            if found.is_some() {
                // Second match - ambiguous
                return Err(ResolveError::Ambiguous);
            }
            found = Some(id);
        }

        found.ok_or(ResolveError::NotFound)
    }

    // ========================================================================
    // Symbol mutation (with automatic event emission)
    // ========================================================================

    /// Register new symbol (emits SymbolAdded event)
    ///
    /// Returns None if registration fails (e.g., duplicate path).
    pub fn register(&mut self, path: SymbolPath, kind: SymbolKind) -> Option<SymbolId> {
        match self.symbol_registry.register(path.clone(), kind) {
            Ok(id) => {
                self.emit_added(path, kind);
                Some(id)
            }
            Err(_) => None,
        }
    }

    /// Register new symbol with AST (emits SymbolAdded event)
    ///
    /// Returns None if registration fails.
    pub fn register_with_ast(
        &mut self,
        path: SymbolPath,
        kind: SymbolKind,
        ast: PureItem,
    ) -> Option<SymbolId> {
        let id = self.register(path, kind)?;
        self.set_ast(id, ast);
        Some(id)
    }

    /// Remove symbol (emits SymbolRemoved event)
    ///
    /// This removes the symbol from:
    /// 1. SymbolRegistry (path → id mapping)
    /// 2. ASTRegistry items (id → PureItem mapping)
    /// 3. Parent module's module_items list (for file generation)
    pub fn remove_symbol(&mut self, id: SymbolId) -> Option<PureItem> {
        if let Some(path) = self.symbol_registry.path(id).cloned() {
            let name = path.name().to_string();

            // Remove from parent module's module_items
            if let Some(parent_path) = path.parent() {
                if let Some(parent_id) = self.symbol_registry.lookup(&parent_path) {
                    if let Some(items) = self.ast_registry.get_module_items_mut(parent_id) {
                        items.retain(|item| !item_matches_name(item, &name));
                    }
                }
            }

            self.symbol_registry.remove(id);
            let ast = self.ast_registry.remove(id);
            self.emit_removed(path);
            ast
        } else {
            None
        }
    }

    /// Rename symbol (emits SymbolRenamed event)
    pub fn rename_symbol(&mut self, id: SymbolId, new_path: SymbolPath) -> Result<(), String> {
        if let Some(old_path) = self.symbol_registry.path(id).cloned() {
            self.symbol_registry
                .rename(id, new_path.clone())
                .map_err(|e| format!("{:?}", e))?;
            self.emit_renamed(old_path, new_path);
            Ok(())
        } else {
            Err("Symbol not found".to_string())
        }
    }
}

/// Check if a PureItem matches the given name.
///
/// Used by `remove_symbol` to filter out items from parent's module_items.
fn item_matches_name(item: &PureItem, name: &str) -> bool {
    match item {
        PureItem::Fn(f) => f.name == name,
        PureItem::Struct(s) => s.name == name,
        PureItem::Enum(e) => e.name == name,
        PureItem::Const(c) => c.name == name,
        PureItem::Static(s) => s.name == name,
        PureItem::Type(t) => t.name == name,
        PureItem::Trait(t) => t.name == name,
        PureItem::Mod(m) => m.name == name,
        PureItem::Impl(i) => {
            // Impl blocks use special naming: "<impl Type>" or "<impl Trait for Type>"
            let impl_name = if let Some(ref trait_name) = i.trait_ {
                format!("<impl {} for {}>", trait_name, i.self_ty)
            } else {
                format!("<impl {}>", i.self_ty)
            };
            impl_name == name
        }
        // Use statements don't have names in the symbol registry sense
        PureItem::Use(_) | PureItem::Macro(_) | PureItem::Other(_) | PureItem::Verbatim(_) => false,
    }
}

#[cfg(test)]
mod tests {
    // TODO: Add tests once apply_v2 is implemented on mutations
}