hakorune/REFACTORING_ANALYSIS_REPORT.md

Nyash Codebase Refactoring Analysis Report

Executive Summary

This report analyzes the Nyash codebase for refactoring opportunities, focusing on large files, duplicate patterns, plugin loader consolidation, and dead code removal. The analysis was conducted manually using grep, find, and file analysis tools due to Docker unavailability for nekocode.

Key Findings

1. Large Files Requiring Splitting

Largest Files (1000+ lines):

• src/mir/builder.rs (1517 lines) - MIR builder with mixed responsibilities
• src/interpreter/plugin_loader.rs (1217 lines) - Plugin loading logic
• src/interpreter/expressions/calls.rs (1016 lines) - Method call handling
• src/interpreter/core.rs (1012 lines) - Core interpreter functionality
• src/ast.rs (1012 lines) - AST definitions and implementations
• src/backend/vm.rs (991 lines) - VM execution engine
• src/runtime/plugin_loader_v2.rs (906 lines) - V2 plugin loader

2. Plugin Loader Consolidation Opportunities

Multiple Plugin Loading Systems Detected:

• src/interpreter/plugin_loader.rs - Original plugin loader
• src/runtime/plugin_loader_v2.rs - V2 plugin loader
• src/runtime/plugin_loader_legacy.rs - Legacy plugin loader
• src/bin/test_plugin_loader_v2.rs - Test implementation

Issues Identified:

• Code duplication across 3+ plugin loader implementations
• Inconsistent FFI handling patterns
• Redundant memory management in FileBoxHandle, MathBoxHandle, RandomBoxHandle
• Complex TLV handling duplicated across loaders

3. Duplicate Code Patterns

Box Implementation Patterns:

• 67 impl NyashBox implementations with similar structure
• Repeated constructor patterns (.new() implementations)
• Common drop/finalization patterns across Box types
• Similar error handling patterns across modules

Common Anti-patterns:

• Excessive .clone() usage (797 instances across files)
• 36 #[allow(dead_code)] suppressions
• 797 instances of potentially unsafe operations (unreachable, panic, unwrap)

4. Dead Code Analysis

Dead Code Indicators:

• 36 explicit dead code suppressions
• Multiple TODO/FIXME comments (20+ instances)
• Unused imports and deprecated methods
• Legacy code paths maintained alongside new implementations

Specific Refactoring Recommendations

Priority 1: Plugin Loader Consolidation

Goal: Merge 3 plugin loaders into unified system

Steps:

1. Create unified PluginLoaderV3 in src/runtime/plugin_loader_unified.rs
2. Extract common FFI patterns into src/runtime/plugin_ffi_common.rs
3. Consolidate handle management (FileBoxHandle, MathBoxHandle, etc.) into generic PluginHandle<T>
4. Migrate existing code incrementally
5. Remove legacy loaders

Impact: ~2000 lines reduction, improved maintainability

Priority 2: MIR Builder Modularization

Goal: Split src/mir/builder.rs (1517 lines) into focused modules

Proposed Structure:

src/mir/builder/
├── mod.rs                 # Public interface and coordination
├── expressions.rs         # Expression lowering (exists, enhance)
├── statements.rs          # Statement lowering
├── control_flow.rs        # If/loop/match lowering
├── type_operations.rs     # Type checking and casting
├── phi_insertion.rs       # SSA phi node management
├── optimization.rs        # Basic optimization passes
└── validation.rs          # Builder state validation

Impact: Improved maintainability, easier testing, clearer separation of concerns

Priority 3: Interpreter Core Splitting

Goal: Break down large interpreter files

Strategy:

• src/interpreter/core.rs → Split into context.rs, execution.rs, environment.rs
• src/interpreter/expressions/calls.rs → Extract static methods, stdlib integration
• Create src/interpreter/dispatch/ module for method dispatch logic

Priority 4: Box Pattern Standardization

Goal: Reduce duplication in Box implementations

Actions:

1. Create BoxMacros proc-macro for common patterns
2. Standardize constructor patterns
3. Extract common drop/finalization logic
4. Create Box trait bounds helpers

Technical Debt Remediation

Error Handling Improvements

• Replace unwrap() with proper error propagation (797 instances)
• Standardize error types across modules
• Implement consistent error context

Memory Management

• Audit .clone() usage for performance impact
• Implement Cow<T> where appropriate
• Optimize Arc/Rc usage patterns

Dead Code Removal

• Remove 36 dead code suppressions systematically
• Clean up TODO/FIXME comments (convert to GitHub issues)
• Remove deprecated method implementations

Implementation Roadmap

Phase 1: Foundation (Week 1-2)

• Create unified plugin loader interfaces
• Extract common FFI patterns
• Set up modular structure for MIR builder

Phase 2: Migration (Week 3-4)

• Migrate existing plugin usage to unified loader
• Split MIR builder into modules
• Begin interpreter core modularization

Phase 3: Optimization (Week 5-6)

• Implement Box pattern standardization
• Remove dead code systematically
• Performance audit and optimization

Phase 4: Validation (Week 7-8)

• Comprehensive testing of refactored code
• Performance benchmarking
• Documentation updates

Risk Assessment

Low Risk:

• Dead code removal
• Documentation improvements
• Box pattern standardization

Medium Risk:

• MIR builder modularization
• Interpreter splitting
• Memory management optimizations

High Risk:

• Plugin loader consolidation (affects external plugins)
• Error handling refactor (wide-reaching changes)

Success Metrics

• Code Quality: Reduce cyclomatic complexity by 30%
• Maintainability: Reduce average file size from 500+ to <300 lines
• Performance: No regression in benchmark performance
• Reliability: Maintain 100% test coverage
• Developer Experience: Reduce onboarding time for new contributors

Conclusion

The Nyash codebase shows signs of rapid development with opportunities for significant refactoring. The plugin loader consolidation offers the highest impact for maintenance improvement, while the MIR builder modularization will improve long-term extensibility. A phased approach is recommended to minimize disruption while delivering incremental benefits.

The analysis reveals a well-architected system that would benefit from tactical refactoring to improve maintainability without compromising the innovative "Everything is Box" design philosophy.

---

Phase 15 Addendum (Mainline only)

• Implemented: extracted CLI directives scanning and fields-top lint into src/runner/cli_directives.rs to slim src/runner/mod.rs without behavior changes.
• Proposed next steps (non-JIT): see docs/development/refactoring/candidates_phase15.md for focused items on Runner/LLVM/VM.