hakorune/src/mir/join_ir/lowering/simple_while_minimal.rs

//! Phase 188-Impl-1: Pattern 1 (Simple While Loop) Minimal Lowerer
//!
//! Target: apps/tests/loop_min_while.hako
//!
//! Code:
//! ```nyash
//! static box Main {
//!   main() {
//!     local i = 0
//!     loop(i < 3) {
//!       print(i)
//!       i = i + 1
//!     }
//!     return 0
//!   }
//! }
//! ```
//!
//! Expected JoinIR:
//! ```text
//! fn main():
//!   i_init = 0
//!   result = loop_step(i_init)
//!   return 0
//!
//! fn loop_step(i):
//!   exit_cond = !(i < 3)
//!   Jump(k_exit, [], cond=exit_cond)  // early return if i >= 3
//!   print(i)                          // body
//!   i_next = i + 1                    // increment
//!   Call(loop_step, [i_next])         // tail recursion
//!
//! fn k_exit():
//!   return 0
//! ```
//!
//! ## Design Notes
//!
//! This is a MINIMAL implementation targeting loop_min_while.hako specifically.
//! It establishes the infrastructure for Pattern 1 lowering, which will be
//! generalized in future phases.
//!
//! Following the "80/20 rule" from CLAUDE.md - get it working first, generalize later.

use crate::mir::join_ir::lowering::loop_scope_shape::LoopScopeShape;
use crate::mir::join_ir::{
    BinOpKind, CompareOp, ConstValue, JoinContId, JoinFuncId, JoinFunction, JoinInst, JoinModule,
    MirLikeInst, UnaryOp,
};
use crate::mir::ValueId;

/// Context passed from the host function to the Pattern 1 lowerer
///
/// Phase 188-Impl-3: This context is now REMOVED - JoinIR uses only local ValueIds
/// The boundary mapping is handled by JoinInlineBoundary instead.
#[deprecated(since = "188-Impl-3", note = "Use JoinInlineBoundary for host integration")]
pub struct Pattern1Context {
    /// DEPRECATED: This is no longer used, JoinIR uses local ValueIds
    pub loop_var: ValueId,
    /// DEPRECATED: JoinIR allocates sequentially from 0
    pub value_allocator: Box<dyn FnMut() -> ValueId>,
}

impl Pattern1Context {
    /// Create a standalone context with hardcoded ValueIds (for backward compatibility)
    pub fn standalone() -> Self {
        let mut counter = 0u32;
        Self {
            loop_var: ValueId(counter),
            value_allocator: Box::new(move || {
                counter += 1;
                ValueId(counter)
            }),
        }
    }
}

/// Lower Pattern 1 (Simple While Loop) to JoinIR
///
/// # Phase 188-Impl-3: Pure JoinIR Fragment Generation
///
/// This version generates JoinIR using **local ValueIds only** (0, 1, 2, ...).
/// It has NO knowledge of the host function's ValueId space. The boundary mapping
/// is handled separately via JoinInlineBoundary.
///
/// ## Design Philosophy
///
/// - **Box A**: JoinIR Frontend (doesn't know about host ValueIds)
/// - **Box B**: This function - converts to JoinIR with local IDs
/// - **Box C**: JoinInlineBoundary - stores boundary info
/// - **Box D**: merge_joinir_mir_blocks - injects Copy instructions
///
/// This clean separation ensures JoinIR lowerers are:
/// - Pure transformers (no side effects)
/// - Reusable (same lowerer works in any context)
/// - Testable (can test JoinIR independently)
///
/// # Arguments
///
/// * `_scope` - LoopScopeShape (reserved for future generic implementation)
/// * `_ctx` - DEPRECATED: No longer used, kept for backward compatibility
///
/// # Returns
///
/// * `Some(JoinModule)` - Successfully lowered to JoinIR
/// * `None` - Pattern not matched (fallback to other lowerers)
///
/// # Boundary Contract
///
/// This function returns a JoinModule with:
/// - **Input slot**: ValueId(0) in loop_step function represents the loop variable
/// - **Caller responsibility**: Create JoinInlineBoundary to map ValueId(0) to host's loop var
pub fn lower_simple_while_minimal(
    _scope: LoopScopeShape,
    _ctx: Option<Pattern1Context>,
) -> Option<JoinModule> {
    // Phase 188-Impl-3: Use local ValueId allocator (sequential from 0)
    // JoinIR has NO knowledge of host ValueIds - boundary handled separately
    let mut value_counter = 0u32;
    let mut alloc_value = || {
        let id = ValueId(value_counter);
        value_counter += 1;
        id
    };

    let mut join_module = JoinModule::new();

    // ==================================================================
    // Function IDs allocation
    // ==================================================================
    let main_id = JoinFuncId::new(0);
    let loop_step_id = JoinFuncId::new(1);
    let k_exit_id = JoinFuncId::new(2);

    // ==================================================================
    // ValueId allocation (Phase 188-Impl-3: Sequential local IDs)
    // ==================================================================
    // main() locals
    let i_init = alloc_value();       // ValueId(0) - loop init value
    let loop_result = alloc_value();  // ValueId(1) - result from loop_step
    let const_0_main = alloc_value(); // ValueId(2) - return value

    // loop_step locals
    let i_param = alloc_value();      // ValueId(3) - parameter
    let const_3 = alloc_value();      // ValueId(4) - comparison constant
    let cmp_lt = alloc_value();       // ValueId(5) - i < 3
    let exit_cond = alloc_value();    // ValueId(6) - !(i < 3)
    let const_1 = alloc_value();      // ValueId(7) - increment constant
    let i_next = alloc_value();       // ValueId(8) - i + 1

    // k_exit locals
    let const_0_exit = alloc_value(); // ValueId(9) - exit return value

    // ==================================================================
    // main() function
    // ==================================================================
    // Phase 188-Impl-3: main() takes i as a parameter (boundary input)
    // The host will inject a Copy instruction: i_init_local = Copy host_i
    let mut main_func = JoinFunction::new(main_id, "main".to_string(), vec![i_init]);

    // result = loop_step(i_init)
    main_func.body.push(JoinInst::Call {
        func: loop_step_id,
        args: vec![i_init],
        k_next: None,
        dst: Some(loop_result),
    });

    // return 0
    main_func.body.push(JoinInst::Compute(MirLikeInst::Const {
        dst: const_0_main,
        value: ConstValue::Integer(0),
    }));

    main_func.body.push(JoinInst::Ret {
        value: Some(const_0_main),
    });

    join_module.add_function(main_func);

    // ==================================================================
    // loop_step(i) function
    // ==================================================================
    let mut loop_step_func = JoinFunction::new(
        loop_step_id,
        "loop_step".to_string(),
        vec![i_param],
    );

    // exit_cond = !(i < 3)
    // Step 1: const 3
    loop_step_func
        .body
        .push(JoinInst::Compute(MirLikeInst::Const {
            dst: const_3,
            value: ConstValue::Integer(3),
        }));

    // Step 2: cmp_lt = (i < 3)
    loop_step_func
        .body
        .push(JoinInst::Compute(MirLikeInst::Compare {
            dst: cmp_lt,
            op: CompareOp::Lt,
            lhs: i_param,
            rhs: const_3,
        }));

    // Step 3: exit_cond = !cmp_lt
    loop_step_func
        .body
        .push(JoinInst::Compute(MirLikeInst::UnaryOp {
            dst: exit_cond,
            op: UnaryOp::Not,
            operand: cmp_lt,
        }));

    // Jump(k_exit, [], cond=exit_cond)
    loop_step_func.body.push(JoinInst::Jump {
        cont: k_exit_id.as_cont(),
        args: vec![],
        cond: Some(exit_cond),
    });

    // print(i)
    // Phase 188-Impl-1-E: Use Print instruction
    loop_step_func
        .body
        .push(JoinInst::Compute(MirLikeInst::Print {
            value: i_param,
        }));

    // i_next = i + 1
    // Step 1: const 1
    loop_step_func
        .body
        .push(JoinInst::Compute(MirLikeInst::Const {
            dst: const_1,
            value: ConstValue::Integer(1),
        }));

    // Step 2: i_next = i + 1
    loop_step_func
        .body
        .push(JoinInst::Compute(MirLikeInst::BinOp {
            dst: i_next,
            op: BinOpKind::Add,
            lhs: i_param,
            rhs: const_1,
        }));

    // Call(loop_step, [i_next])  // tail recursion
    loop_step_func.body.push(JoinInst::Call {
        func: loop_step_id,
        args: vec![i_next],
        k_next: None,  // CRITICAL: None for tail call
        dst: None,
    });

    join_module.add_function(loop_step_func);

    // ==================================================================
    // k_exit() function
    // ==================================================================
    let mut k_exit_func = JoinFunction::new(k_exit_id, "k_exit".to_string(), vec![]);

    // return 0 (Pattern 1 has no exit values)
    // Phase 188-Impl-3: Use pre-allocated const_0_exit (ValueId(9))
    k_exit_func.body.push(JoinInst::Compute(MirLikeInst::Const {
        dst: const_0_exit,
        value: ConstValue::Integer(0),
    }));

    k_exit_func.body.push(JoinInst::Ret {
        value: Some(const_0_exit),
    });

    join_module.add_function(k_exit_func);

    // Set entry point
    join_module.entry = Some(main_id);

    eprintln!("[joinir/pattern1] Generated JoinIR for Simple While Pattern");
    eprintln!("[joinir/pattern1] Functions: main, loop_step, k_exit");

    Some(join_module)
}