hakorune/src/mir/loop_pattern_detection.rs

//! Loop Pattern Detection Module
//!
//! Phase 188 Task 188-4: Pattern detection helpers for JoinIR loop lowering.
//!
//! This module provides detection functions for 3 loop patterns:
//! - Pattern 1: Simple While Loop (foundational)
//! - Pattern 2: Loop with Conditional Break (early exit)
//! - Pattern 3: Loop with If-Else PHI (variable mutation)
//!
//! These functions are "thin boxes" that take LoopForm and return bool.
//! No side effects, pure detection logic.
//!
//! Reference: docs/private/roadmap2/phases/phase-188-joinir-loop-pattern-expansion/design.md

use crate::mir::loop_form::LoopForm;

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

/// Detect Pattern 1: Simple While Loop
///
/// Returns true ONLY if:
/// - Loop condition is simple comparison (no &&, ||)
/// - Loop body contains only assignments + prints (no nested loops, no breaks)
/// - Loop has single increment/decrement
/// - NO break statements (break_targets is empty)
/// - NO continue statements (continue_targets is empty)
/// - Single backedge (latches.len() == 1)
///
/// # Arguments
/// * `loop_form` - The loop structure to analyze
///
/// # Returns
/// * `true` if the loop matches Pattern 1 (Simple While), `false` otherwise
///
/// # Reference
/// See design.md § Pattern 1 → LoopScopeShape Recognition
///
/// # Example
/// ```rust,ignore
/// let loop_form = /* ... */;
/// if is_simple_while_pattern(&loop_form) {
///     // Lower to simple while pattern
/// }
/// ```
pub fn is_simple_while_pattern(loop_form: &LoopForm) -> bool {
    // Pattern 1 Recognition Criteria (from design.md § Pattern 1):
    // 1. break_targets: EMPTY (no break statements)
    // 2. continue_targets: EMPTY (no continue statements)
    // 3. Single backedge (single latch - LoopShape has singular latch field)
    //
    // Note: LoopShape has a singular `latch` field, not `latches`, so we don't
    // need to check length. The existence of a LoopShape implies a valid latch.

    // Check 1: No break statements
    if !loop_form.break_targets.is_empty() {
        return false;
    }

    // Check 2: No continue statements
    if !loop_form.continue_targets.is_empty() {
        return false;
    }

    // Check 3: All other checks passed
    // The LoopShape structure guarantees:
    // - Single preheader, header, body, latch, exit
    // - Valid loop structure
    //
    // Pattern 1 ONLY requires:
    // - No breaks, no continues
    // - Natural loop structure (which LoopShape guarantees)
    //
    // Advanced checks (nested loops, complex conditions) are deferred to
    // lowering phase where we can fail gracefully if needed.

    true
}

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

/// Detect Pattern 2: Loop with Conditional Break
///
/// Returns true ONLY if:
/// - Loop condition exists
/// - Loop body contains exactly ONE if statement with break
/// - Break is in then-branch
/// - NO nested loops
/// - break_targets is NON-EMPTY (has at least one break)
///
/// # Arguments
/// * `loop_form` - The loop structure to analyze
///
/// # Returns
/// * `true` if the loop matches Pattern 2 (Break), `false` otherwise
///
/// # Reference
/// See design.md § Pattern 2 → LoopScopeShape Recognition
///
/// # Example
/// ```rust,ignore
/// let loop_form = /* ... */;
/// if is_loop_with_break_pattern(&loop_form) {
///     // Lower to loop with break pattern
/// }
/// ```
pub fn is_loop_with_break_pattern(loop_form: &LoopForm) -> bool {
    // TODO: Implement detection logic
    // Step 1: Check break_targets is NON-EMPTY
    // Step 2: Check exactly ONE break target (len() == 1)
    // Step 3: Find if statement containing break
    // Step 4: Verify break is in then-branch
    // Step 5: Verify no nested loops
    //
    // Reference: design.md § Pattern 2 section
    // Recognition Criteria:
    // - break_targets: NON-EMPTY (at least 1 break)
    // - continue_targets: EMPTY (for simplicity)
    // - Exactly one if statement with break
    //
    // Example LoopScopeShape:
    // ```rust
    // LoopScopeShape {
    //     preheader: BlockId(1),
    //     header: BlockId(2),
    //     body: BlockId(3),
    //     latch: BlockId(5),
    //     exit: BlockId(6),
    //     break_targets: vec![BlockId(4)],  // NON-EMPTY - CRITICAL CHECK
    //     continue_targets: vec![],         // EMPTY
    // }
    // ```
    false
}

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

/// Detect Pattern 3: Loop with If-Else PHI
///
/// Returns true ONLY if:
/// - Loop has if-else statement assigning to variable(s)
/// - Both branches assign to same variable
/// - NO nested loops
/// - NO break or continue statements
/// - Loop has multiple carrier variables (e.g., i + sum)
///
/// # Arguments
/// * `loop_form` - The loop structure to analyze
///
/// # Returns
/// * `true` if the loop matches Pattern 3 (If-Else PHI), `false` otherwise
///
/// # Reference
/// See design.md § Pattern 3 → LoopScopeShape Recognition
///
/// # Example
/// ```rust,ignore
/// let loop_form = /* ... */;
/// if is_loop_with_conditional_phi_pattern(&loop_form) {
///     // Lower to loop with if-else phi pattern
/// }
/// ```
pub fn is_loop_with_conditional_phi_pattern(loop_form: &LoopForm) -> bool {
    // TODO: Implement detection logic
    // Step 1: Check break_targets is EMPTY (no breaks)
    // Step 2: Check continue_targets is EMPTY (no continues)
    // Step 3: Find if-else statement in body
    // Step 4: Verify both branches assign to same variable
    // Step 5: Verify loop has multiple carrier variables
    // Step 6: Verify no nested loops
    //
    // Reference: design.md § Pattern 3 section
    // Recognition Criteria:
    // - break_targets: EMPTY
    // - continue_targets: EMPTY
    // - Body contains if-else assigning to variable
    // - Multiple carrier variables (e.g., i + sum)
    //
    // Example LoopScopeShape:
    // ```rust
    // LoopScopeShape {
    //     preheader: BlockId(1),
    //     header: BlockId(2),
    //     body: BlockId(3),   // Contains if-else with variable assignment
    //     latch: BlockId(7),
    //     exit: BlockId(8),
    //     break_targets: vec![],        // EMPTY - CRITICAL CHECK
    //     continue_targets: vec![],     // EMPTY - CRITICAL CHECK
    // }
    // ```
    false
}

// ============================================================================
// Helper Functions (Future Use)
// ============================================================================

/// Count the number of carrier variables in a loop
///
/// Carrier variables are loop variables that are updated in the loop body
/// and carried through PHI nodes in the header.
///
/// # Arguments
/// * `loop_form` - The loop structure to analyze
///
/// # Returns
/// * Number of carrier variables
///
/// # TODO
/// Implement by analyzing header PHI nodes
#[allow(dead_code)]
fn count_carrier_variables(loop_form: &LoopForm) -> usize {
    // TODO: Implement carrier variable counting
    // Step 1: Access loop_form.header block
    // Step 2: Count PHI instructions in header
    // Step 3: Return count
    0
}

/// Check if loop body contains nested loops
///
/// # Arguments
/// * `loop_form` - The loop structure to analyze
///
/// # Returns
/// * `true` if nested loops found, `false` otherwise
///
/// # TODO
/// Implement by checking for LoopForm within body blocks
#[allow(dead_code)]
fn has_nested_loops(loop_form: &LoopForm) -> bool {
    // TODO: Implement nested loop detection
    // Step 1: Traverse body blocks
    // Step 2: Check for loop headers in body
    // Step 3: Return true if any found
    false
}

/// Check if loop condition is simple (single comparison, no && or ||)
///
/// # Arguments
/// * `loop_form` - The loop structure to analyze
///
/// # Returns
/// * `true` if condition is simple, `false` otherwise
///
/// # TODO
/// Implement by checking header condition complexity
#[allow(dead_code)]
fn has_simple_condition(loop_form: &LoopForm) -> bool {
    // TODO: Implement condition complexity check
    // Step 1: Access loop_form.header block
    // Step 2: Find condition instruction
    // Step 3: Check for && or || operators
    // Step 4: Return true if no complex operators
    true // Assume simple for now
}

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

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

    #[test]
    #[ignore] // TODO: Implement test after detection logic is complete
    fn test_pattern1_simple_while_detection() {
        // TODO: Add unit test for simple while pattern detection
        // Step 1: Create mock LoopForm with:
        //   - Empty break_targets
        //   - Empty continue_targets
        //   - Single latch
        // Step 2: Call is_simple_while_pattern()
        // Step 3: Assert returns true
    }

    #[test]
    #[ignore] // TODO: Implement test after detection logic is complete
    fn test_pattern1_rejects_break() {
        // TODO: Add test that rejects loop with break
        // Step 1: Create mock LoopForm with non-empty break_targets
        // Step 2: Call is_simple_while_pattern()
        // Step 3: Assert returns false
    }

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

    #[test]
    #[ignore] // TODO: Implement test after detection logic is complete
    fn test_pattern2_break_detection() {
        // TODO: Add unit test for break pattern detection
        // Step 1: Create mock LoopForm with:
        //   - Non-empty break_targets (exactly 1)
        //   - Empty continue_targets
        //   - If statement with break
        // Step 2: Call is_loop_with_break_pattern()
        // Step 3: Assert returns true
    }

    #[test]
    #[ignore] // TODO: Implement test after detection logic is complete
    fn test_pattern2_rejects_no_break() {
        // TODO: Add test that rejects loop without break
        // Step 1: Create mock LoopForm with empty break_targets
        // Step 2: Call is_loop_with_break_pattern()
        // Step 3: Assert returns false
    }

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

    #[test]
    #[ignore] // TODO: Implement test after detection logic is complete
    fn test_pattern3_if_else_phi_detection() {
        // TODO: Add unit test for if-else phi pattern detection
        // Step 1: Create mock LoopForm with:
        //   - Empty break_targets
        //   - Empty continue_targets
        //   - If-else statement in body
        //   - Multiple carrier variables
        // Step 2: Call is_loop_with_conditional_phi_pattern()
        // Step 3: Assert returns true
    }

    #[test]
    #[ignore] // TODO: Implement test after detection logic is complete
    fn test_pattern3_rejects_break() {
        // TODO: Add test that rejects loop with break
        // Step 1: Create mock LoopForm with non-empty break_targets
        // Step 2: Call is_loop_with_conditional_phi_pattern()
        // Step 3: Assert returns false
    }
}