hakorune/docs/refactor-roadmap.md

# Nyash Refactor Roadmap (Pre–Self-Hosting)

This document lists large modules, proposes safe splits/commonization, and outlines the MIR13 cleanup plan.

## Large Modules to Split

Targets are chosen by size and cohesion. Splits are incremental and build-preserving; move code in small steps and re-export in `mod.rs`.

- `src/mir/verification.rs` (~965 loc)
  - Split into: `mir/verification/{mod.rs,basic.rs,types.rs,control_flow.rs,ownership.rs}`.
  - First move leaf helpers and pass-specific checks; keep public API and `pub use` to avoid churn.

- `src/mir/builder.rs` (~930 loc)
  - Split into: `mir/builder/{mod.rs,exprs.rs,stmts.rs,decls.rs,control_flow.rs}`.
  - Extract expression/statement builders first. Keep tests (if any) colocated.

- `src/mir/instruction.rs` (~896 loc)
  - Near-term: introduce `mir/instruction/{mod.rs,core.rs,ops.rs,calls.rs}` without changing the enum surface.
  - Medium-term: migrate to MIR13 (see below) and delete legacy variants.

- `src/mir/optimizer.rs` (~875 loc)
  - Split passes into: `mir/optimizer/{mod.rs,constant_folding.rs,dead_code.rs,inline.rs,type_inference.rs}`.
  - Keep a simple pass runner that sequences the modules.

- `src/runner/mod.rs` (~885 loc)
  - Extract modes into `runner/modes/{vm.rs,jit.rs,mir_interpreter.rs,llvm.rs}` if not already, and move glue to `runner/lib.rs`.
  - Centralize CLI arg parsing in a dedicated module.

- `src/backend/vm_instructions/boxcall.rs` (~881 loc)
  - Group by box domain: `boxcall/{array.rs,map.rs,ref.rs,weak.rs,plugin.rs,core.rs}`.
  - Long-term: most of these become `BoxCall` handlers driven by method ID tables.

## MIR13 Cleanup Plan

A large portion of pre-MIR13 variants remain. Current occurrences:

- ArrayGet: 11, ArraySet: 11
- RefNew: 8, RefGet: 15, RefSet: 17
- TypeCheck: 13, Cast: 13
- PluginInvoke: 14, Copy: 13, Debug: 8, Print: 10, Nop: 9, Throw: 12, Catch: 13, Safepoint: 14

Phased migration (mechanical, testable per phase):

1) Introduce shims
   - Add `BoxCall` helpers covering array/ref/weak/map ops and plugin methods.
   - Add `TypeOp::{Check,Cast}` modes to map legacy `TypeCheck/Cast`.

2) Replace uses (non-semantic changes)
   - Replace within: `backend/dispatch.rs`, `backend/mir_interpreter.rs`, `backend/cranelift/*`, `backend/wasm/codegen.rs`, `mir/printer.rs`, tests.
   - Keep legacy variants in enum but mark Deprecated for a short period.

3) Tighten verification/optimizer
   - Update `verification.rs` to reason about `BoxCall/TypeOp` only.
   - Update optimizer patterns (e.g., fold Copy → Load/Store; drop Nop/Safepoint occurrences).

4) Delete legacy variants
   - Remove `ArrayGet/Set, RefNew/Get/Set, PluginInvoke, TypeCheck, Cast, Copy, Debug, Print, Nop, Throw, Catch, Safepoint`.
   - Update discriminant printer and state dumps accordingly.

Use `tools/mir13-migration-helper.sh` to generate per-file tasks and verify.

## Commonization Opportunities

- Backend dispatch duplication
  - `backend/dispatch.rs`, `backend/vm.rs`, and Cranelift JIT lowerings handle overlapping instruction sets. Centralize instruction semantics interfaces (traits) and keep backend-specific execution and codegen in adapters.

- Method ID resolution
  - `runtime/plugin_loader_v2` and backend call sites both compute/lookup method IDs. Provide a single resolver module with caching shared by VM/JIT/LLVM.

- CLI/runtime bootstrap
  - Move repeated plugin host init/logging messages into a small `runtime/bootstrap.rs` with a single `init_plugins(&Config)` entry point used by all modes.

## Suggested Order of Work

1. Split `mir/verification` and `mir/builder` into submodules (no behavior changes).
2. Add `BoxCall` shims and `TypeOp` modes; replace printer/dispatch/codegen uses.
3. Update verification/optimizer for the unified ops.
4. Delete legacy variants and clean up dead code.
5. Tackle `runner/mod.rs` and `backend/vm_instructions/boxcall.rs` splits.

Each step should compile independently and run `tools/smoke_vm_jit.sh` to validate VM/JIT basics.