hakorune/docs/development/refactoring/modularization-directory-structure.md

Modularization Directory Structure Diagrams

Visual reference for the proposed directory structures after modularization.

---

1. control_flow.rs Modularization

Before (Current State)

src/mir/builder/
├── control_flow.rs                    (1,632 lines) ⚠️ MONOLITH
├── if_form.rs
├── loops.rs
└── ... (other files)

After (Proposed Structure)

src/mir/builder/
├── control_flow/
│   ├── mod.rs                         (~150 lines) ✅ Entry points
│   │   ├── pub(super) fn cf_block()
│   │   ├── pub(super) fn cf_if()
│   │   ├── pub(super) fn cf_loop()
│   │   ├── pub(super) fn cf_try_catch()
│   │   └── pub(super) fn cf_throw()
│   │
│   ├── debug.rs                       (~50 lines) ✅ Debug utilities
│   │   └── fn trace_varmap()
│   │
│   ├── utils.rs                       (~50 lines) ✅ Utility functions
│   │   └── fn extract_loop_variable_from_condition()
│   │
│   ├── joinir/
│   │   ├── mod.rs                     (~100 lines) ✅ JoinIR coordinator
│   │   │
│   │   ├── routing.rs                 (~150 lines) ✅ Routing logic
│   │   │   ├── fn try_cf_loop_joinir()
│   │   │   └── fn cf_loop_joinir_impl()
│   │   │
│   │   ├── merge/
│   │   │   ├── mod.rs                 (~100 lines) ✅ Merge coordinator
│   │   │   │   └── pub fn merge_joinir_mir_blocks()
│   │   │   │
│   │   │   ├── id_remapper.rs         (~150 lines) ✅ ID remapping
│   │   │   │   ├── struct JoinIrIdRemapper
│   │   │   │   ├── fn create_remapper()
│   │   │   │   └── fn remap_ids()
│   │   │   │
│   │   │   ├── block_allocator.rs     (~100 lines) ✅ Block allocation
│   │   │   │   └── fn allocate_blocks()
│   │   │   │
│   │   │   ├── value_collector.rs     (~100 lines) ✅ Value collection
│   │   │   │   └── fn collect_values()
│   │   │   │
│   │   │   ├── instruction_rewriter.rs (~150 lines) ✅ Instruction rewriting
│   │   │   │   ├── fn rewrite_instructions()
│   │   │   │   └── fn convert_call_to_jump()
│   │   │   │
│   │   │   └── exit_phi_builder.rs    (~100 lines) ✅ Exit PHI construction
│   │   │       └── fn build_exit_phi()
│   │   │
│   │   └── patterns/
│   │       ├── mod.rs                 (~50 lines) ✅ Pattern dispatcher
│   │       │   └── pub fn dispatch_pattern()
│   │       │
│   │       ├── pattern1_minimal.rs    (~150 lines) ✅ Pattern 1 lowering
│   │       │   └── pub fn cf_loop_pattern1_minimal()
│   │       │
│   │       ├── pattern2_with_break.rs (~130 lines) ✅ Pattern 2 lowering
│   │       │   └── pub fn cf_loop_pattern2_with_break()
│   │       │
│   │       └── pattern3_with_if_phi.rs (~180 lines) ✅ Pattern 3 lowering
│   │           └── pub fn cf_loop_pattern3_with_if_phi()
│   │
│   └── exception/
│       ├── mod.rs                     (~50 lines) ✅ Exception API
│       │
│       ├── try_catch.rs               (~150 lines) ✅ try/catch impl
│       │   └── pub fn cf_try_catch()
│       │
│       └── throw.rs                   (~30 lines) ✅ throw impl
│           └── pub fn cf_throw()
│
├── if_form.rs
├── loops.rs
└── ... (other files - unchanged)

Metrics Comparison

Metric	Before	After	Change
Total lines	1,632	~1,850	+13% (for clarity)
Number of files	1	19	+1800%
Largest file	1,632	~180	-89%
Average file size	1,632	~97	-94%
Functions per file	13	1-2	Much clearer

Benefits

• ✅ 714-line merge function → 6 focused modules (100-150 lines each)
• ✅ Pattern lowerers isolated → Easy to add Pattern 4/5/6
• ✅ Debug traces easier to locate → NYASH_OPTION_C_DEBUG output clearer
• ✅ Merge conflicts reduced → Changes isolated to specific files
• ✅ Code navigation improved → Jump to definition works better

---

2. generic_case_a.rs Modularization

Before (Current State)

src/mir/join_ir/lowering/
├── generic_case_a.rs                      (1,056 lines) ⚠️ LARGE
├── generic_case_a_entry_builder.rs        (4,828 bytes)
├── generic_case_a_whitespace_check.rs     (4,552 bytes)
└── ... (other files)

After (Proposed Structure)

src/mir/join_ir/lowering/
├── generic_case_a/
│   ├── mod.rs                             (~100 lines) ✅ Public API
│   │   ├── pub use skip_ws::lower_case_a_skip_ws_with_scope
│   │   ├── pub use trim::lower_case_a_trim_with_scope
│   │   ├── pub use append_defs::lower_case_a_append_defs_with_scope
│   │   └── pub use stage1_using_resolver::...
│   │
│   ├── skip_ws.rs                         (~220 lines) ✅ skip_ws lowerer
│   │   ├── pub fn lower_case_a_skip_ws_with_scope()
│   │   └── fn lower_case_a_skip_ws_core()
│   │
│   ├── trim.rs                            (~500 lines) ✅ trim lowerer
│   │   ├── pub fn lower_case_a_trim_with_scope()
│   │   └── fn lower_case_a_trim_core()
│   │
│   ├── append_defs.rs                     (~170 lines) ✅ append_defs lowerer
│   │   ├── pub fn lower_case_a_append_defs_with_scope()
│   │   └── fn lower_case_a_append_defs_core()
│   │
│   ├── stage1_using_resolver.rs          (~180 lines) ✅ stage1 lowerer
│   │   ├── pub fn lower_case_a_stage1_usingresolver_with_scope()
│   │   └── fn lower_case_a_stage1_usingresolver_core()
│   │
│   ├── entry_builder.rs                   (~150 lines) ✅ (moved from parent)
│   │   └── struct EntryFunctionBuilder
│   │
│   └── whitespace_check.rs                (~150 lines) ✅ (moved from parent)
│       └── fn check_whitespace()
│
└── ... (other files - unchanged)

Metrics Comparison

Metric	Before	After	Change
Total lines	1,056	~1,470	+39% (for clarity)
Number of files	3 (scattered)	7 (organized)	+133%
Largest file	1,056	~500	-53%
Average file size	352	~210	-40%
Functions per file	4	1-2	Much clearer

Benefits

• ✅ Each lowerer in its own file → Easy to maintain
• ✅ Companion files integrated → All Case A logic in one directory
• ✅ trim.rs still large (500 lines) → Could be further split if needed
• ✅ Clear public API → mod.rs shows what's exported

---

3. loopform_builder.rs Modularization

Before (Current State - After Phase 191)

src/mir/phi_core/
├── loopform_builder.rs                    (1,166 lines) ⚠️ LARGE
├── loopform_context.rs                    (✅ already modularized)
├── loopform_variable_models.rs            (✅ already modularized)
├── loopform_utils.rs                      (✅ already modularized)
├── loopform_exit_phi.rs                   (✅ already modularized)
└── ... (other files)

After (Proposed Structure)

src/mir/phi_core/
├── loopform/
│   ├── mod.rs                             (~100 lines) ✅ Public API
│   │   ├── pub use context::LoopFormContext
│   │   ├── pub use variable_models::{CarrierVariable, PinnedVariable}
│   │   ├── pub use exit_phi::build_exit_phis_for_control
│   │   └── pub use builder_core::LoopFormBuilder
│   │
│   ├── context.rs                         (~150 lines) ✅ (existing)
│   │   └── pub struct LoopFormContext
│   │
│   ├── variable_models.rs                 (~150 lines) ✅ (existing)
│   │   ├── pub struct CarrierVariable
│   │   ├── pub struct PinnedVariable
│   │   └── pub struct LoopBypassFlags
│   │
│   ├── utils.rs                           (~100 lines) ✅ (existing)
│   │   ├── pub fn is_loopform_debug_enabled()
│   │   └── pub fn get_loop_bypass_flags()
│   │
│   ├── exit_phi.rs                        (~150 lines) ✅ (existing)
│   │   └── pub fn build_exit_phis_for_control()
│   │
│   ├── passes/
│   │   ├── mod.rs                         (~50 lines) ✅ 4-pass coordinator
│   │   │   └── pub fn run_4_pass_architecture()
│   │   │
│   │   ├── pass1_discovery.rs             (~150 lines) ✅ Variable discovery
│   │   │   └── pub fn discover_variables()
│   │   │
│   │   ├── pass2_header_phi.rs            (~150 lines) ✅ Header PHI
│   │   │   └── pub fn build_header_phi()
│   │   │
│   │   ├── pass3_latch.rs                 (~100 lines) ✅ Latch processing
│   │   │   └── pub fn process_latch()
│   │   │
│   │   └── pass4_exit_phi.rs              (~150 lines) ✅ Exit PHI
│   │       └── pub fn build_exit_phi()
│   │
│   └── builder_core.rs                    (~200 lines) ✅ Core builder
│       └── pub struct LoopFormBuilder
│
└── ... (other files - unchanged)

Metrics Comparison

Metric	Before	After	Change
Total lines	1,166 (main file)	~1,450	+24% (for clarity)
Number of files	5 (partially modularized)	11 (fully modularized)	+120%
Largest file	1,166	~200	-83%
Average file size	233	~132	-43%

Benefits

• ✅ Completes Phase 191 modularization → Finishes what was started
• ✅ 4-pass architecture explicit → Each pass in its own file
• ✅ Already partially modularized → Lower risk than control_flow.rs
• ✅ Clear separation of concerns → Context, models, passes, builder

---

File Size Distribution Comparison

control_flow.rs

Before:
█████████████████████████████████████████████████████████████████ 1,632 lines

After:
merge/instruction_rewriter.rs: ███████ 150 lines
pattern1_minimal.rs:           ███████ 150 lines
routing.rs:                    ███████ 150 lines
pattern3_with_if_phi.rs:       ████████ 180 lines
try_catch.rs:                  ███████ 150 lines
... (14 more files < 150 lines each)

generic_case_a.rs

Before:
███████████████████████████████████████████████████ 1,056 lines

After:
trim.rs:                       ████████████████████████ 500 lines
skip_ws.rs:                    ██████████ 220 lines
stage1_using_resolver.rs:      ████████ 180 lines
append_defs.rs:                ████████ 170 lines
... (3 more files < 150 lines each)

loopform_builder.rs

Before:
████████████████████████████████████████████████████████ 1,166 lines

After:
builder_core.rs:               █████████ 200 lines
context.rs:                    ███████ 150 lines
variable_models.rs:            ███████ 150 lines
exit_phi.rs:                   ███████ 150 lines
pass1_discovery.rs:            ███████ 150 lines
... (6 more files < 150 lines each)

---

Import Path Changes

control_flow.rs

Before

use crate::mir::builder::MirBuilder;

impl MirBuilder {
    pub(super) fn cf_loop(...) -> Result<ValueId, String> {
        // 1,632 lines of code
    }
}

After

// src/mir/builder/control_flow/mod.rs
use crate::mir::builder::MirBuilder;

impl MirBuilder {
    pub(super) fn cf_loop(...) -> Result<ValueId, String> {
        // Delegates to routing module
        joinir::routing::try_cf_loop_joinir(self, ...)
    }
}

// src/mir/builder/control_flow/joinir/routing.rs
pub(in crate::mir::builder::control_flow) fn try_cf_loop_joinir(
    builder: &mut MirBuilder,
    ...
) -> Result<Option<ValueId>, String> {
    // 150 lines of focused code
}

generic_case_a.rs

Before

// src/mir/join_ir/lowering/generic_case_a.rs
pub(crate) fn lower_case_a_skip_ws_with_scope(...) -> Option<JoinModule> {
    // 200+ lines
}

After

// src/mir/join_ir/lowering/generic_case_a/mod.rs
pub(crate) use skip_ws::lower_case_a_skip_ws_with_scope;

// src/mir/join_ir/lowering/generic_case_a/skip_ws.rs
pub(crate) fn lower_case_a_skip_ws_with_scope(...) -> Option<JoinModule> {
    // 220 lines
}

loopform_builder.rs

Before

// src/mir/phi_core/loopform_builder.rs
pub use loopform_context::LoopFormContext;

pub fn build_exit_phis_for_control<O: LoopFormOps>(...) {
    // 1,166 lines
}

After

// src/mir/phi_core/loopform/mod.rs
pub use context::LoopFormContext;
pub use exit_phi::build_exit_phis_for_control;

// src/mir/phi_core/loopform/exit_phi.rs
pub fn build_exit_phis_for_control<O: LoopFormOps>(...) {
    // 150 lines
}

---

Navigation Improvements

Before (Monolith Files)

Developer: "Where is the merge function?"
Answer: "control_flow.rs, line 864-1578 (search through 1,632 lines)"

Developer: "Where is Pattern 3 lowering?"
Answer: "control_flow.rs, line 696-863 (search through 1,632 lines)"

Developer: "What does merge_joinir_mir_blocks do?"
Answer: "Read 714 lines to understand"

After (Modularized)

Developer: "Where is the merge function?"
Answer: "control_flow/joinir/merge/mod.rs (100 lines coordinator)"

Developer: "Where is Pattern 3 lowering?"
Answer: "control_flow/joinir/patterns/pattern3_with_if_phi.rs (180 lines)"

Developer: "What does merge_joinir_mir_blocks do?"
Answer: "Read merge/mod.rs (100 lines) → delegates to 6 sub-modules"

---

Conclusion

The modularization dramatically improves code organization:

• control_flow.rs: 1,632 lines → 19 files (avg 97 lines)
• generic_case_a.rs: 1,056 lines → 7 files (avg 210 lines)
• loopform_builder.rs: 1,166 lines → 11 files (avg 132 lines)

Total Impact: 3,854 lines → 37 focused modules

Developer Experience:

• ✅ Easier navigation (jump to definition works better)
• ✅ Clearer separation of concerns
• ✅ Less merge conflicts
• ✅ Easier to add new patterns/lowerers
• ✅ Better code review experience (smaller diffs)

---

Last Updated: 2025-12-05