hakorune/docs/development/current/main/REFACTORING_OPPORTUNITIES.md

Refactoring Opportunities Analysis

Date: 2025-12-12 Status: Comprehensive audit complete Total Opportunities: 10 (3 HIGH, 4 MEDIUM, 3 LOW) Estimated Combined Impact: 2,600+ lines of duplicate/dead/incomplete code

---

Executive Summary

Refactoring audit identified 10 code quality opportunities across the codebase. Ranked by impact and risk, with detailed recommendations for each.

Key Finding: Most opportunities are about consolidation (duplicate logic, monolithic files) rather than dead code removal.

---

HIGH-IMPACT Opportunities

1. Extern Dispatch Consolidation (722 + 481 lines duplicated)

Location:

• src/backend/mir_interpreter/handlers/calls/global.rs (236 lines)
• src/backend/mir_interpreter/handlers/calls/externs.rs (73 lines)

Problem: VM interpreter implements print/error/panic/exit dispatch in TWO locations:

• execute_global_function() - routes via global function table
• execute_extern_function() - direct builtin handler

Current Pattern (GOOD):

• global.rs lines 87-102: Delegates to execute_extern_function for print/panic/exit
• global.rs line 91-96: Direct error handling (eprintln!)
• externs.rs lines 19-71: All print/error/panic/exit implementations

Analysis:

• ✅ ALREADY optimized - global.rs delegates most calls
• ⚠️ Minor issue: error not in externs.rs, only direct in global.rs (line 91-96)
• ⚠️ Duplicate inline implementations in externs.rs (lines 19-63)

Recommendation: SAFE - Keep current delegation pattern, consider extracting print/panic/exit to unified dispatch_builtin() helper. LOW-RISK refactor (1-2 hours).

Risk: MODERATE (changes core VM logic) Effort: MEDIUM (extract + test) Status: Deferred to Phase 65+ (not on critical path)

---

2. Monolithic Files Splitting (Phase 33 Box-First Modularization)

Key Files:

• src/mir/join_ir/lowering/normalized.rs (1,269 lines)
• src/mir/join_ir/lowering/merge/mod.rs (1,072 lines)
• src/runner/modes/common_util/resolve/strip.rs (1,081 lines)
• src/backend/boxes/file/handle_box.rs (1,072 lines)

Problem: Large modules mixing multiple concerns (orchestration, analysis, transformation).

Example (merge/mod.rs):

• Lines 1-100: Core orchestrator
• Lines 101-300: Variable mapping logic
• Lines 301-600: Instruction rewriting
• Lines 601-1072: Meta collection & finalization

Recommendation: Split into semantic boxes (e.g., merge/mod.rs → orchestrator.rs, variable_mapper.rs, instruction_rewriter.rs, meta_collector.rs)

Risk: SAFE (can refactor incrementally with unit tests) Effort: LARGE (3-6 months for all 4 files) Status: Deferred to Phase 100+ (long-term structural improvement) Value: Improved maintainability, testability, developer velocity

---

3. WASM Executor Cleanup (206 lines, TODO comments)

Location: src/backend/executor (fully commented out with // mod executor; // TODO: Fix WASM executor build errors)

Problem: WASM executor disabled with no clear deprecation status.

Decision Needed: Keep or remove?

Recommendation:

1. Option A: Remove (206 lines saved) - if WASM not on roadmap
2. Option B: Re-enable (requires investigating "build errors")
3. Option C: Defer to Phase 150+ (not critical for VM/LLVM dual pillar)

Current Status: Phase 15 NOT on critical path per analysis Risk: LOW (no active code) Effort: SMALL (remove) or MEDIUM (re-enable) Value: Clarity on WASM direction

Recommendation: Option C - defer decision until Phase 100+ (post-selfhosting milestone)

---

MEDIUM-IMPACT Opportunities

4. BID-Codegen Stubs Decision

Location: src/bid-codegen-from-copilot/codegen/targets/

Files:

• typescript.rs (16 lines stub) - Imported in generator.rs, dispatched via CodeGenTarget::TypeScript
• python.rs (16 lines stub) - Imported in generator.rs, dispatched via CodeGenTarget::Python
• llvm.rs (16 lines stub) - Imported in generator.rs, dispatched via CodeGenTarget::LLVM

Status: All print "🚧 X code generation not yet implemented" and return empty vec

Problem: Decision ambiguous: keep stubs or feature-gate/remove?

Recommendation:

1. Option A: Keep as-is (no risk, but clutters codebase)
2. Option B: Add documentation comments + feature-gate behind #[cfg(feature = "bid_codegen_legacy")]
3. Option C: Replace with explicit panic on use + deprecation note in generator.rs

Current Assessment: TypeScript/Python/LLVM generators NOT on Phase 15 critical path. Keep stubs to preserve API surface (downstream may depend on CodeGenTarget variants).

Risk: LOW (isolated stubs) Effort: SMALL (add docs/feature gate) or TINY (remove) Value: Clarity on BID-codegen roadmap

Recommendation: Option B - add deprecation comments documenting replacement path (via llvmlite harness or future implementation)

---

5. Plugin Loader Unification (469 lines)

Location: src/runtime/plugin_loader_unified.rs

Status: Thin wrapper over v2 loader (plugin_loader_v2.rs)

Methods: load_libraries(), load_library_direct(), resolve_method(), create_box(), invoke_instance_method(), extern_call()

Analysis:

• ✅ Clean abstraction layer (good design)
• ⚠️ Wrapper overhead - could migrate callers directly to v2
• ⚠️ Redundancy - 469 lines to wrap ~300 lines of v2

Recommendation: Audit call sites (src/runner/modes/, src/backend/, etc.) to understand if wrapper adds value. If NOT, consider gradual migration to v2 API.

Risk: MODERATE (plugin system is critical) Effort: SMALL-MEDIUM (audit + gradual migration) Value: Reduced indirection, clearer ownership

Current Status: Keep wrapper until v2 API proven stable (Phase 15 adoption in progress)

---

6. loop_patterns_old Module Status

Location: src/mir/join_ir/frontend/ast_lowerer/loop_patterns_old.rs (914 lines)

Status: ACTIVE in production (NOT dead code)

Usage:

• Imported in mod.rs (line in ast_lowerer/mod.rs)
• Called in loop_frontend_binding.rs via lowerer.lower_loop_with_break_continue(program_json)
• Used in analysis.rs for test/dev analysis

Functions:

• lower_loop_with_break_continue() - main entry
• lower_loop_case_a_simple() - Case A (tiny loops)
• lower_loop_break_pattern() - Break pattern handling
• lower_loop_continue_pattern() - Continue pattern handling

Assessment: This module IS actively used as fallback for loop patterns. NOT dead code.

Recommendation: KEEP (actively maintained fallback path)

---

7. allow(dead_code) Audit (298 annotations)

Status: Scattered across 26 files

Sample Files:

• src/config/ - Multiple suppressions
• src/mir/join_ir/ - Phase-specific suppressions
• src/backend/boxes/ - Box implementations

Analysis: Over-suppressed code likely indicates:

1. Legacy features kept for compatibility
2. Test-only code not in test features
3. Unused trait implementations

Recommendation: Systematic audit - remove obvious annotations, mark intentional ones with comments explaining WHY.

Risk: LOW (no behavior change) Effort: MEDIUM (requires careful review per file) Value: Clearer signal-to-noise ratio in compiler output

Current Status: Deferred to Phase 70+ (polish, not critical)

---

LOW-IMPACT Opportunities

8. AOT Backend Incomplete (3,980 lines total)

Location: src/aot/

Status: Partial implementation with TODOs:

• compile_to_executable() - not implemented
• Link phase - incomplete
• Optimization pipeline - limited

Assessment: AOT not on Phase 15 critical path (LLVM harness is primary)

Recommendation: DEFER or REMOVE depending on roadmap. Phase 15 focuses on VM + LLVM, not AOT ahead-of-time compilation.

Risk: MODERATE (large codebase) Effort: LARGE (cleanup or completion) Value: Clarity on AOT vs LLVM strategy

Current Status: Keep for now (may be useful for distribution), but mark as experimental.

---

9. Test Infrastructure Cleanup

Minor issues:

• Some test fixtures use legacy patterns
• Test utilities scattered across multiple modules

Recommendation: DEFER to Phase 75+ (low-priority polish)

---

10. Using System TODOs (Minor)

Status: Minimal TODOs found (using/namespace system largely complete per CLAUDE.md Phase 15.5)

Current Assessment: Most using/namespace work COMPLETE (git commit 4120ab65 StringBox recovery, 3d082ca1 env propagation)

Recommendation: MONITOR for Phase 65+ namespace order SSOT work

---

Summary Recommendation Matrix

Item	Impact	Risk	Effort	Status
Extern Dispatch Consolidation	HIGH	MODERATE	MEDIUM	Defer Phase 65+
Monolithic Files Splitting	HIGH	SAFE	LARGE (3-6m)	Defer Phase 100+
WASM Executor Decision	HIGH	LOW	SMALL	Defer Phase 150+
BID-Codegen Stubs	MEDIUM	LOW	SMALL	Document
Plugin Loader Unification	MEDIUM	MODERATE	SMALL-MEDIUM	Defer Phase 20+
loop_patterns_old Audit	MEDIUM	SAFE	TINY	✅ KEEP (ACTIVE)
allow(dead_code) Cleanup	MEDIUM	LOW	MEDIUM	Defer Phase 70+
AOT Backend Status	LOW	MODERATE	LARGE	Clarify roadmap
Test Infrastructure	LOW	SAFE	SMALL	Defer Phase 75+
Using System TODOs	LOW	SAFE	TINY	Monitor Phase 65+

---

Quick Wins (< 2 hours each)

1. Add deprecation comments to BID-codegen stubs (+15 lines, -0 breaking)

   • Document replacement path (llvmlite harness)
   • Add migration guide for future TypeScript/Python implementations

2. Document loop_patterns_old purpose (+10 lines)

   • Clarify role as fallback pattern handler
   • Link to Pattern1-4 normalized version

3. Clarify WASM executor status (+5 lines)

   • Decision note in executor/mod.rs
   • Link to Phase 150+ roadmap

---

Long-Term Strategy

Post-Phase 64 Ownership Architecture:

1. Phase 65+: Relay support (owned variable initialization, carrier order SSOT)
2. Phase 70-75: Code quality pass (dead_code audit, test infrastructure, using system)
3. Phase 100+: Monolithic files refactoring (Box-First modularization of merge/mod.rs, strip.rs, etc.)
4. Phase 150+: WASM/AOT/BID-codegen decision (clarity on roadmap)

---

Notes

• All recommendations are deferrable - no blocking issues found
• Most high-impact items are structural (monolithic files) not functional (bugs)
• Current code quality is GOOD relative to project age (4 months)
• Priorities align with Phase 15 Rust VM + LLVM dual pillar focus

Last audit: 2025-12-12 via Explore agent cc45cd20