hakorune/src/mir/join_ir/lowering/loop_patterns/mod.rs

//! Phase 33-12: Loop Pattern Lowering Module
//!
//! Implements JoinIR lowering for different loop patterns:
//! - Pattern 1: Simple while loops (no break/continue)
//! - Pattern 2: Loops with break statements
//! - Pattern 3: Loops with if expressions + PHI merging
//! - Pattern 4: Loops with continue statements (stub)
//!
//! # Module Structure
//!
//! Each pattern is implemented in its own file:
//! - `simple_while.rs`: Pattern 1 implementation
//! - `with_break.rs`: Pattern 2 implementation
//! - `with_if_phi.rs`: Pattern 3 implementation
//! - `with_continue.rs`: Pattern 4 stub
//!
//! # Design Philosophy
//!
//! Pattern lowering functions are "thin boxes":
//! - Takes input (LoopForm, builder)
//! - Returns Result (success/error)
//! - No side effects outside the builder
//!
//! # Reference
//!
//! Design document: `docs/private/roadmap2/phases/phase-188-joinir-loop-pattern-expansion/design.md`

pub mod simple_while;
pub mod with_break;
pub mod with_if_phi;
pub mod with_continue;

pub use simple_while::lower_simple_while_to_joinir;
pub use with_break::lower_loop_with_break_to_joinir;
pub use with_if_phi::lower_loop_with_conditional_phi_to_joinir;
pub use with_continue::lower_loop_with_continue_to_joinir;

// ============================================================================
// Helper Functions (Shared Utilities)
// ============================================================================

// TODO: Implement helper functions for extraction and translation
// These will be shared across all 4 patterns:
//
// 1. extract_carriers_from_header_phi(loop_form) -> Vec<CarrierVar>
// 2. extract_loop_condition_from_header(loop_form) -> ValueId
// 3. extract_body_instructions(loop_form) -> Vec<MirInstruction>
// 4. translate_mir_inst_to_joinir(inst, lowerer) -> JoinInst
// 5. find_break_block(loop_form) -> BasicBlockId
// 6. extract_break_condition(block) -> ValueId
// 7. find_if_else_block(loop_form) -> BasicBlockId
// 8. extract_if_condition(block) -> ValueId
// 9. extract_then_value(block) -> ValueId
// 10. extract_else_value(block) -> ValueId

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

    // ========================================================================
    // Pattern 1: Simple While Loop Tests
    // ========================================================================

    #[test]
    #[ignore] // TODO: Implement test after lowering logic is complete
    fn test_pattern1_lowering_success() {
        // TODO: Add integration test for simple while pattern lowering
        // Step 1: Create mock LoopForm for simple while pattern
        // Step 2: Create mock LoopToJoinLowerer
        // Step 3: Call lower_simple_while_to_joinir()
        // Step 4: Assert returns Some(JoinInst)
        // Step 5: Verify generated JoinIR structure
    }

    #[test]
    #[ignore] // TODO: Implement test after lowering logic is complete
    fn test_pattern1_rejects_break() {
        // TODO: Add test that rejects loop with break
        // Step 1: Create mock LoopForm with break
        // Step 2: Call lower_simple_while_to_joinir()
        // Step 3: Assert returns None (unsupported pattern)
    }

    // ========================================================================
    // Pattern 2: Loop with Break Tests
    // ========================================================================

    #[test]
    #[ignore] // TODO: Implement test after lowering logic is complete
    fn test_pattern2_lowering_success() {
        // TODO: Add integration test for break pattern lowering
        // Step 1: Create mock LoopForm for break pattern
        // Step 2: Create mock LoopToJoinLowerer
        // Step 3: Call lower_loop_with_break_to_joinir()
        // Step 4: Assert returns Some(JoinInst)
        // Step 5: Verify generated JoinIR structure (two Jumps to k_exit)
    }

    #[test]
    #[ignore] // TODO: Implement test after lowering logic is complete
    fn test_pattern2_exit_phi_correct() {
        // TODO: Add test that verifies k_exit receives correct exit values
        // Step 1: Create mock LoopForm for break pattern
        // Step 2: Call lower_loop_with_break_to_joinir()
        // Step 3: Verify k_exit params = [i_exit]
        // Step 4: Verify both Jumps pass current i as argument
    }

    // ========================================================================
    // Pattern 3: Loop with If-Else PHI Tests
    // ========================================================================

    #[test]
    #[ignore] // TODO: Implement test after lowering logic is complete
    fn test_pattern3_lowering_success() {
        // TODO: Add integration test for if-else phi pattern lowering
        // Step 1: Create mock LoopForm for if-else phi pattern
        // Step 2: Create mock LoopToJoinLowerer
        // Step 3: Call lower_loop_with_conditional_phi_to_joinir()
        // Step 4: Assert returns Some(JoinInst)
        // Step 5: Verify generated JoinIR structure (Select instruction)
    }

    #[test]
    #[ignore] // TODO: Implement test after lowering logic is complete
    fn test_pattern3_multiple_carriers() {
        // TODO: Add test that verifies multiple carrier variables
        // Step 1: Create mock LoopForm with i + sum carriers
        // Step 2: Call lower_loop_with_conditional_phi_to_joinir()
        // Step 3: Verify loop_step params = [i, sum]
        // Step 4: Verify tail Call args = [i_next, sum_new]
    }

    #[test]
    #[ignore] // TODO: Implement test after lowering logic is complete
    fn test_pattern3_if_lowering_integration() {
        // TODO: Add test that verifies If lowering integration
        // Step 1: Create mock LoopForm with if-else
        // Step 2: Call lower_loop_with_conditional_phi_to_joinir()
        // Step 3: Verify Select instruction is generated
        // Step 4: Verify Select has correct cond/then_val/else_val
    }

    // ========================================================================
    // Pattern 4: Loop with Continue Tests
    // ========================================================================

    #[test]
    #[ignore] // TODO: Implement test after lowering logic is complete
    fn test_pattern4_lowering_success() {
        // TODO: Add integration test for continue pattern lowering
        // Step 1: Create mock LoopForm for continue pattern
        // Step 2: Create mock LoopToJoinLowerer
        // Step 3: Call lower_loop_with_continue_to_joinir()
        // Step 4: Assert returns Some(JoinInst)
        // Step 5: Verify generated JoinIR structure (Jump to loop_step on continue)
    }

    #[test]
    #[ignore] // TODO: Implement test after lowering logic is complete
    fn test_pattern4_continue_jump_correct() {
        // TODO: Add test that verifies continue jumps to loop_step
        // Step 1: Create mock LoopForm for continue pattern
        // Step 2: Call lower_loop_with_continue_to_joinir()
        // Step 3: Verify conditional Jump targets loop_step
        // Step 4: Verify Jump passes current carrier values as arguments
    }

    #[test]
    #[ignore] // TODO: Implement test after lowering logic is complete
    fn test_pattern4_multiple_carriers() {
        // TODO: Add test that verifies multiple carrier variables
        // Step 1: Create mock LoopForm with i + sum carriers
        // Step 2: Call lower_loop_with_continue_to_joinir()
        // Step 3: Verify loop_step params = [i, sum]
        // Step 4: Verify both tail Call and continue Jump use [i_next, sum_next]
    }
}