refactor(joinir): Phase 183-3 Document LoopScopeShape construction paths

Clarifies that LoopScopeShape has two complementary construction paths
for different contexts (AST-based vs LoopForm-based).

## Analysis

After investigating, discovered these builders serve **different purposes**:

1. **AST-based** (`patterns/loop_scope_shape_builder.rs`):
   - Builds from AST during MIR generation
   - Extracts body_locals from ASTNode::Local declarations
   - Used in Pattern 1-4 lowerers

2. **LoopForm-based** (`loop_scope_shape/builder.rs`):
   - Builds from LoopForm during JoinIR lowering
   - Analyzes LoopFormIntake snapshots
   - Used in generic_case_a and pattern routing

These are NOT duplicates - they're complementary paths!

## Changes

1. **Cross-Reference Documentation**:
   - `patterns/loop_scope_shape_builder.rs`: Added Phase 183-3 section
   - `loop_scope_shape/builder.rs`: Added Phase 183-3 section
   - Both now reference each other for clarity

2. **LoopScopeShape Struct Documentation**:
   - Added "Phase 183-3: Construction Paths" section
   - Documents two construction paths and their contexts
   - Explains when to use each builder

3. **Clarified Responsibilities**:
   - AST-based: For MIR building phase
   - LoopForm-based: For JoinIR lowering phase
   - Both maintain consistent field initialization

## Benefits

- **Clear separation**: Documented different contexts for each builder
- **Maintainability**: Future developers understand which builder to use
- **No code changes**: Pure documentation improvement
- **Cross-references**: Easy navigation between related modules

## Testing

 All loop_scope_shape tests pass (24 tests)
 No behavioral changes
 Documentation-only refactoring

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
nyash-codex
2025-12-08 22:22:25 +09:00
parent a32791b0ed
commit 94bf00faf9
3 changed files with 31 additions and 1 deletions

View File

@ -1,4 +1,4 @@
//! LoopScopeShapeBuilder - Unified LoopScopeShape initialization
//! LoopScopeShapeBuilder - AST-based LoopScopeShape initialization
//!
//! Phase 171-172: Issue 4
//!
@ -11,6 +11,14 @@
//! - Extract body_locals from loop body AST when needed
//! - Maintain consistent initialization defaults across patterns
//!
//! # Phase 183-3: AST-Based Construction Context
//!
//! This builder constructs LoopScopeShape from **AST nodes** during MIR building.
//! For LoopForm-based construction (JoinIR lowering), see:
//! - `src/mir/join_ir/lowering/loop_scope_shape/builder.rs`
//!
//! Both builders maintain consistent field initialization for LoopScopeShape.
//!
//! # Usage
//!
//! ```rust