ryo-executor 0.1.0

//! ASTRegApply trait - Apply mutations to ASTRegistry
//!
//! This trait extends Mutation with registry-based execution capability.
//! Defined in ryo-executor to avoid circular dependency between
//! ryo-mutations and ryo-analysis.
//!
//! # Design
//!
//! ```text
//! ryo-mutations          ryo-analysis           ryo-executor
//! ┌──────────────┐      ┌──────────────┐       ┌──────────────┐
//! │ Mutation     │      │ ASTRegistry  │       │ ASTRegApply  │
//! │ (base trait) │      │ SymbolReg    │       │ (ext trait)  │
//! └──────────────┘      └──────────────┘       └──────────────┘
//!        ↑                     ↑                      │
//!        └─────────────────────┴──────────────────────┘
//!                    ASTRegApply: Mutation
//! ```
//!
//! # Quality Policy for V2 Implementations
//!
//! When implementing `ASTRegApply` for mutations:
//!
//! ## DO:
//! - Design the implementation to work naturally with ASTRegistry/SymbolRegistry
//! - Add comprehensive snapshot tests that verify exact output
//! - Consider if the ASTMutationContext API needs extension for new capabilities
//!
//! ## DON'T:
//! - Create hacky workarounds just to make tests pass
//! - Use temporary allocations or intermediate representations (defeats V2 purpose)
//! - Copy V1 patterns that don't fit the registry-based model
//!
//! ## When V2 Cannot Handle a Mutation Cleanly:
//!
//! If a mutation cannot be implemented cleanly with the current V2 API:
//!
//! 1. **Do NOT** hack the implementation or tests to force it to work
//! 2. **Do** evaluate if ASTMutationContext needs new methods
//! 3. **Do** consider if ASTRegistry/SymbolRegistry need enhancements
//! 4. **Do** document the design gap and propose a proper solution
//!
//! The goal is a clean, maintainable architecture - not 100% feature coverage
//! through workarounds.
//!
//! # Usage
//!
//! ```ignore
//! use ryo_executor::engine::ASTRegApply;
//!
//! impl ASTRegApply for AddFieldMutation {
//!     fn apply_to_registry(&self, ctx: &mut ASTMutationContext) -> MutationResult {
//!         // Get target struct from registry
//!         let id = ctx.lookup(&self.target_path)?;
//!         let ast = ctx.get_ast_mut(id)?;
//!
//!         // Modify AST
//!         if let PureItem::Struct(s) = ast {
//!             s.fields.push(new_field);
//!         }
//!
//!         ctx.emit_modified(id, ModificationType::FieldAdded(name));
//!         MutationResult { ... }
//!     }
//! }
//! ```

use ryo_mutations::{Mutation, MutationResult};

use super::ast_mutation_engine::ASTMutationContext;

/// Trait for mutations that can be applied to ASTRegistry
///
/// Extends the base `Mutation` trait with registry-based execution.
/// This is the primary execution path for the new AST-centric architecture.
///
/// # Implementing
///
/// Mutations that want to support registry-based execution should:
/// 1. Implement this trait
/// 2. Use `ctx.lookup()` to find target symbols
/// 3. Use `ctx.get_ast_mut()` to modify AST
/// 4. Use `ctx.emit_*()` to record changes
///
/// # Fallback
///
/// If a mutation doesn't implement this trait, ASTMutationEngine
/// will return no changes. The legacy `apply(&mut PureFile)` path
/// remains available for backward compatibility.
pub trait ASTRegApply: Mutation {
    /// Apply this mutation to the ASTRegistry
    ///
    /// # Arguments
    ///
    /// * `ctx` - Mutable context providing access to registries and event emission
    ///
    /// # Returns
    ///
    /// MutationResult indicating the number of changes made
    fn apply_to_registry(&self, ctx: &mut ASTMutationContext) -> MutationResult;
}