docs(joinir): Add Phase 179-B Generic Pattern Framework design

docs/development/current/main/phase179-generic-pattern-framework.md

@@ -0,0 +1,374 @@
+# Phase 179-B: Generic Pattern Framework Design
+
+**Status**: Implementation in progress
+**Related**: Phase 33-22 (CommonPatternInitializer), Phase 171-172 (Builders)
+
+## Objective
+
+Unify the preprocessing pipeline for Patterns 1-4 by creating a `PatternPipelineContext` that consolidates all pattern initialization logic into a single, reusable "解析済みコンテキスト箱" (analyzed context box).
+
+## Current State Analysis
+
+### Pattern Initialization Breakdown (Lines)
+
+| Pattern | File | Total Lines | Preprocessing | Lowering | Target |
+|---------|------|-------------|---------------|----------|--------|
+| Pattern 1 | pattern1_minimal.rs | 139 | ~61 | ~78 | ~15 |
+| Pattern 3 | pattern3_with_if_phi.rs | 169 | ~151 | ~18 | ~30 |
+| Pattern 2 | pattern2_with_break.rs | 517 | ~437 | ~80 | ~80 |
+| Pattern 4 | pattern4_with_continue.rs | 433 | ~363 | ~70 | ~70 |
+
+**Total Reduction Target**: ~1012 lines → ~195 lines (**81% reduction**)
+
+### Existing Infrastructure
+
+We already have excellent modular components:
+- **CommonPatternInitializer**: Loop variable extraction + CarrierInfo initialization
+- **LoopScopeShapeBuilder**: LoopScopeShape construction (with/without body_locals)
+- **ConditionEnvBuilder**: ConditionEnv + ConditionBinding construction
+- **Pattern4CarrierAnalyzer**: Carrier filtering and update analysis
+
+## Design: PatternPipelineContext
+
+### Core Principles
+
+1. **Pure Analysis Container**: Only holds preprocessing results, no JoinIR emission
+2. **Analyzer-Only Dependencies**: Only depends on analyzer boxes, never lowering logic
+3. **Pattern-Specific Variants**: Use `Option<T>` for pattern-specific data
+
+### Struct Definition
+
+```rust
+/// Phase 179-B: Unified Pattern Pipeline Context
+///
+/// Pure "解析済みコンテキスト箱" - holds only preprocessing results.
+/// JoinIR emission and PHI assembly remain in existing lowerers.
+///
+/// # Design Constraints
+///
+/// - **Analyzer-only dependencies**: Never depends on lowering logic
+/// - **No emission**: No JoinIR/MIR generation in this context
+/// - **Pattern variants**: Pattern-specific data stored in Option<T>
+///
+/// # Usage
+///
+/// ```rust
+/// let ctx = build_pattern_context(
+///     builder,
+///     condition,
+///     body,
+///     PatternVariant::Pattern1,
+/// )?;
+///
+/// // Use preprocessed data for lowering
+/// let join_module = lower_simple_while_minimal(ctx.loop_scope)?;
+/// ```
+pub struct PatternPipelineContext {
+    // === Common Data (All Patterns) ===
+
+    /// Loop variable name (e.g., "i")
+    pub loop_var_name: String,
+
+    /// Loop variable HOST ValueId
+    pub loop_var_id: ValueId,
+
+    /// Carrier information (loop variable + carriers)
+    pub carrier_info: CarrierInfo,
+
+    /// Loop scope shape (header/body/latch/exit structure)
+    pub loop_scope: LoopScopeShape,
+
+    // === Pattern 2/4: Break/Continue Condition ===
+
+    /// Condition environment (variable → JoinIR ValueId mapping)
+    /// Used by Pattern 2 (break condition) and Pattern 4 (continue condition)
+    pub condition_env: Option<ConditionEnv>,
+
+    /// Condition bindings (HOST↔JoinIR value mappings)
+    /// Used by Pattern 2 and Pattern 4
+    pub condition_bindings: Option<Vec<ConditionBinding>>,
+
+    /// Carrier update expressions (variable → UpdateExpr)
+    /// Used by Pattern 2 (multi-carrier) and Pattern 4 (Select-based updates)
+    pub carrier_updates: Option<HashMap<String, UpdateExpr>>,
+
+    // === Pattern 2/4: Trim Pattern Support ===
+
+    /// Trim loop helper (if Trim pattern detected during promotion)
+    /// Used by Pattern 2 (string trim) - Pattern 4 support TBD
+    pub trim_helper: Option<TrimLoopHelper>,
+
+    // === Pattern 2: Break Condition ===
+
+    /// Effective break condition (may be modified for Trim pattern)
+    /// Used only by Pattern 2
+    pub break_condition: Option<ASTNode>,
+}
+
+/// Pattern variant selector
+pub enum PatternVariant {
+    Pattern1,  // Simple while loop
+    Pattern2,  // Loop with break
+    Pattern3,  // Loop with if-else PHI
+    Pattern4,  // Loop with continue
+}
+```
+
+### Pipeline Function
+
+```rust
+/// Build pattern preprocessing context
+///
+/// This consolidates all preprocessing steps shared by Patterns 1-4:
+/// 1. Loop variable extraction (CommonPatternInitializer)
+/// 2. LoopScopeShape construction (LoopScopeShapeBuilder)
+/// 3. Pattern-specific analysis (ConditionEnv, carrier updates, etc.)
+/// 4. Trim pattern promotion (if applicable)
+///
+/// # Arguments
+///
+/// * `builder` - MirBuilder instance
+/// * `condition` - Loop condition AST node
+/// * `body` - Loop body AST nodes
+/// * `variant` - Pattern variant selector
+///
+/// # Returns
+///
+/// PatternPipelineContext with all preprocessing results
+///
+/// # Errors
+///
+/// Returns error if:
+/// - Loop variable not found in variable_map
+/// - Condition variable not found (Pattern 2/4)
+/// - Trim pattern promotion fails (Pattern 2/4)
+pub fn build_pattern_context(
+    builder: &mut MirBuilder,
+    condition: &ASTNode,
+    body: &[ASTNode],
+    variant: PatternVariant,
+) -> Result<PatternPipelineContext, String> {
+    // Step 1: Common initialization
+    let (loop_var_name, loop_var_id, mut carrier_info) =
+        CommonPatternInitializer::initialize_pattern(
+            builder,
+            condition,
+            &builder.variable_map,
+            None,
+        )?;
+
+    // Step 2: Build LoopScopeShape
+    let loop_scope = match variant {
+        PatternVariant::Pattern1 | PatternVariant::Pattern3 => {
+            // Pattern 1, 3: No body_locals needed
+            LoopScopeShapeBuilder::empty_body_locals(
+                BasicBlockId(0),
+                BasicBlockId(0),
+                BasicBlockId(0),
+                BasicBlockId(0),
+                BTreeSet::new(),
+            )
+        }
+        PatternVariant::Pattern2 | PatternVariant::Pattern4 => {
+            // Pattern 2, 4: Extract body_locals for Trim support
+            LoopScopeShapeBuilder::with_body_locals(
+                BasicBlockId(0),
+                BasicBlockId(0),
+                BasicBlockId(0),
+                BasicBlockId(0),
+                BTreeSet::new(),
+                body,
+            )
+        }
+    };
+
+    // Step 3: Pattern-specific preprocessing
+    let (condition_env, condition_bindings, carrier_updates, trim_helper, break_condition) =
+        match variant {
+            PatternVariant::Pattern1 => {
+                // Pattern 1: No additional preprocessing
+                (None, None, None, None, None)
+            }
+            PatternVariant::Pattern3 => {
+                // Pattern 3: No condition env, but has carrier updates (for if-else PHI)
+                // TODO: Pattern 3 analyzer integration
+                (None, None, None, None, None)
+            }
+            PatternVariant::Pattern2 => {
+                // Pattern 2: Full preprocessing (break condition, carriers, Trim)
+                build_pattern2_context(builder, condition, body, &loop_var_name, loop_var_id, &mut carrier_info, &loop_scope)?
+            }
+            PatternVariant::Pattern4 => {
+                // Pattern 4: Similar to Pattern 2 but with continue semantics
+                build_pattern4_context(builder, condition, body, &loop_var_name, loop_var_id, &mut carrier_info, &loop_scope)?
+            }
+        };
+
+    Ok(PatternPipelineContext {
+        loop_var_name,
+        loop_var_id,
+        carrier_info,
+        loop_scope,
+        condition_env,
+        condition_bindings,
+        carrier_updates,
+        trim_helper,
+        break_condition,
+    })
+}
+```
+
+## Integration Strategy
+
+### Migration Order: P1 → P3 → P2 → P4
+
+1. **Pattern 1** (Minimal complexity)
+   - Zero dependencies on ConditionEnv
+   - Only needs: loop_var_name, loop_var_id, loop_scope
+   - Best for testing the framework
+
+2. **Pattern 3** (PHI without break/continue)
+   - Adds carrier handling for if-else PHI
+   - No break/continue complexity
+   - Tests carrier_info flow
+
+3. **Pattern 2** (Most complex)
+   - Full feature set: break + Trim + multi-carrier
+   - Tests all context fields
+   - Validates Trim pattern integration
+
+4. **Pattern 4** (Continue semantics)
+   - Similar to Pattern 2 but Select-based
+   - Final validation of framework completeness
+
+### Pattern 1 Migration Example
+
+**Before** (61 lines of preprocessing):
+```rust
+pub(in crate::mir::builder) fn cf_loop_pattern1_minimal(
+    &mut self,
+    condition: &ASTNode,
+    _body: &[ASTNode],
+    _func_name: &str,
+    debug: bool,
+) -> Result<Option<ValueId>, String> {
+    // ... 61 lines of initialization ...
+
+    let join_module = lower_simple_while_minimal(scope)?;
+
+    // ... merge and return ...
+}
+```
+
+**After** (~15 lines):
+```rust
+pub(in crate::mir::builder) fn cf_loop_pattern1_minimal(
+    &mut self,
+    condition: &ASTNode,
+    body: &[ASTNode],
+    _func_name: &str,
+    debug: bool,
+) -> Result<Option<ValueId>, String> {
+    // Step 1: Build preprocessing context
+    let ctx = build_pattern_context(
+        self,
+        condition,
+        body,
+        PatternVariant::Pattern1,
+    )?;
+
+    // Step 2: Call lowerer with preprocessed data
+    let join_module = lower_simple_while_minimal(ctx.loop_scope)?;
+
+    // Step 3: Create boundary from context
+    let boundary = JoinInlineBoundaryBuilder::new()
+        .with_inputs(vec![ValueId(0)], vec![ctx.loop_var_id])
+        .with_loop_var_name(Some(ctx.loop_var_name.clone()))
+        .build();
+
+    // Step 4: Merge and return
+    JoinIRConversionPipeline::execute(self, join_module, Some(&boundary), "pattern1", debug)?;
+    Ok(Some(emit_void(self)))
+}
+```
+
+## Trim/P5 Special Case Handling
+
+### Current Situation
+
+Pattern 2 has complex Trim pattern logic (~100 lines) that:
+1. Detects Trim pattern via LoopBodyCarrierPromoter
+2. Generates initial whitespace check
+3. Modifies break condition
+4. Adds carrier to ConditionEnv
+
+### Phase 179-B Strategy
+
+**Include in PatternPipelineContext**:
+- Trim detection and validation (LoopBodyCarrierPromoter)
+- TrimLoopHelper storage
+- Modified break condition
+
+**Keep in Pattern 2 lowerer**:
+- Initial whitespace check emission (MIR instruction generation)
+- This is "lowering" not "analysis"
+
+**Future Phase 180+ (Trim-specific refactor)**:
+- Move Trim lowering logic to `trim_loop_lowering.rs`
+- Create `TrimPatternLowerer` box
+- PatternPipelineContext just provides the analysis result
+
+## Benefits
+
+### Code Reduction
+- **Pattern 1**: 61 → ~15 lines (75% reduction)
+- **Pattern 3**: 151 → ~30 lines (80% reduction)
+- **Pattern 2**: 517 → ~80 lines (85% reduction)
+- **Pattern 4**: 433 → ~70 lines (84% reduction)
+- **Total**: 1162 → ~195 lines (**83% reduction**)
+
+### Maintainability
+- Single source of truth for preprocessing
+- Easier to add new patterns
+- Clear separation: analysis vs lowering
+
+### Testability
+- Can test preprocessing independently
+- Pattern-specific logic isolated
+- Easier to mock/stub for unit tests
+
+### Consistency
+- All patterns use same initialization flow
+- Consistent error messages
+- Uniform trace/debug output
+
+## Non-Goals (Out of Scope)
+
+❌ **Not included in PatternPipelineContext**:
+- JoinIR emission (remains in existing lowerers)
+- PHI assembly (remains in existing lowerers)
+- MIR instruction generation (remains in existing lowerers)
+- Block merging (remains in JoinIRConversionPipeline)
+
+✅ **Only preprocessing**:
+- Variable extraction
+- Carrier analysis
+- Condition environment setup
+- Trim pattern detection
+
+## Implementation Checklist
+
+- [ ] Task 179-B-1: Design document (this file)
+- [ ] Task 179-B-2: PatternPipelineContext implementation
+- [ ] Task 179-B-3: Pattern 1 migration
+- [ ] Task 179-B-4: Pattern 3 migration
+- [ ] Task 179-B-5: Pattern 2 migration
+- [ ] Task 179-B-6: Pattern 4 migration
+- [ ] Task 179-B-7: Tests and documentation update
+
+## References
+
+- **CommonPatternInitializer**: `src/mir/builder/control_flow/joinir/patterns/common_init.rs`
+- **LoopScopeShapeBuilder**: `src/mir/builder/control_flow/joinir/patterns/loop_scope_shape_builder.rs`
+- **ConditionEnvBuilder**: `src/mir/builder/control_flow/joinir/patterns/condition_env_builder.rs`
+- **JoinIRConversionPipeline**: `src/mir/builder/control_flow/joinir/patterns/conversion_pipeline.rs`