diff --git a/docs/development/current/CURRENT_TASK.md b/docs/development/current/CURRENT_TASK.md index 657bcd8c..bf7c9eb2 100644 --- a/docs/development/current/CURRENT_TASK.md +++ b/docs/development/current/CURRENT_TASK.md @@ -127,6 +127,36 @@ tools/ci_check_golden.sh # 代表ケースのMIR含有チェック - `vm_boxcall.rs`: `call_box_method` を移動(`call_unified_method`は現状のまま)。 - 影響最小・挙動非変更で、可読性と責務分離を先行する。 +## 🧭 リファクタリングゴール(AI一目見て分かる導線) + +### 目的/原則 +- 明確責務: 各モジュールが1行で説明できる目的・責務を持つ +- 入口統一: VM/MIRの読む順番が固定され、迷わない +- ファイル肥大防止: 1000行超は段階分割(まずVMホットパス) +- ドキュメント導線: quick-referenceで最短経路を提示 +- 振る舞い不変: すべてのゴールデン/CIが緑 + +### マイルストーン(受入基準) +- M1: VM導線完成(達成) + - vm.rs → vm_instructions.rs → vm_values.rs / vm_boxcall.rs / vm_stats.rs / vm_phi.rs + - code-map(docs/quick-reference/code-map.md)で入口と責務を明記 + - 受入: build OK / golden 緑 / 実行変化なし +- M2: モジュールヘッダ(着手) + - Purpose/Responsibilities/Key APIs/Typical Callers を各VMモジュール先頭に追記 + - 受入: 各モジュール先頭4行程度の要約とcode-mapの整合 +- M3: 1000行級の導線整備(設計メモ) + - interpreter/plugin_loader.rs: v2主導の導線明文化(削除は後) + - interpreter/objects.rs: 可視性/フィールド/ライフサイクルの分割指針をTODO化 +- M4: レガシー移行(土台) + - RESULTBOX_MIGRATION_TODOの維持、VMは新旧両対応のまま + +### 実行順(小さく確実に) +1) M2ヘッダ追加(VM系) +2) M3 plugin_loader 導線の明文化(コメント/TODO/コードマップ) +3) M3 objects.rs 分割設計メモ +4) 用語の統一・code-map追従 +5) golden + 重要E2Eを確認 + ### ⚠️ MIRビルダー引き継ぎポイント(ChatGPT5さんへ) - **状況**: MIRビルダーのモジュール化完了(Phase 1-8コミット済み) - **問題**: MIR命令構造の変更により、expressions.rsでエラー発生 diff --git a/src/backend/vm.rs b/src/backend/vm.rs index 61ef5dc0..ae53d2b5 100644 --- a/src/backend/vm.rs +++ b/src/backend/vm.rs @@ -1,7 +1,10 @@ /*! * VM Backend - Execute MIR instructions in a virtual machine - * - * Simple stack-based VM for executing MIR code + * + * Purpose: Core VM (execute loop, storage, control-flow, integration glue) + * Responsibilities: fetch/dispatch instructions, manage values/blocks, stats hooks + * Key APIs: VM::execute_module, execute_instruction, get_value/set_value + * Typical Callers: runner (VM backend), instruction handlers (vm_instructions) */ use crate::mir::{MirModule, MirFunction, MirInstruction, ConstValue, BinaryOp, CompareOp, UnaryOp, ValueId, BasicBlockId}; diff --git a/src/backend/vm_boxcall.rs b/src/backend/vm_boxcall.rs index fdd326a9..f88fc20b 100644 --- a/src/backend/vm_boxcall.rs +++ b/src/backend/vm_boxcall.rs @@ -1,5 +1,10 @@ /*! - * VM BoxCall Dispatch - method calls on boxes + * VM BoxCall Dispatch + * + * Purpose: Method calls on Box values (dispatch by concrete box type) + * Responsibilities: call_box_method_impl, BoxCall debug logging + * Key APIs: call_box_method_impl, debug_log_boxcall + * Typical Callers: vm_instructions::execute_boxcall / VM::call_unified_method */ use crate::box_trait::{NyashBox, StringBox, IntegerBox, BoolBox, VoidBox}; diff --git a/src/backend/vm_instructions.rs b/src/backend/vm_instructions.rs index 858c7323..22afaafc 100644 --- a/src/backend/vm_instructions.rs +++ b/src/backend/vm_instructions.rs @@ -1,5 +1,10 @@ /*! - * VM Instruction Handlers - Extracted from execute_instruction for better modularity + * VM Instruction Handlers + * + * Purpose: Implementation of each MIR instruction handler (invoked by vm.rs) + * Responsibilities: load/store/branch/phi/call/array/ref/await/extern_call + * Key APIs: execute_const/execute_binop/execute_unaryop/execute_compare/... + * Typical Callers: VM::execute_instruction (dispatch point) */ use crate::mir::{ConstValue, BinaryOp, CompareOp, UnaryOp, ValueId, BasicBlockId, TypeOpKind, MirType}; diff --git a/src/backend/vm_phi.rs b/src/backend/vm_phi.rs index 722b5d98..005f6131 100644 --- a/src/backend/vm_phi.rs +++ b/src/backend/vm_phi.rs @@ -1,8 +1,10 @@ /*! - * VM Phi Node Handler - SSA形式のPhi nodeをVMで正しく実行するモジュール - * - * MIRのloop_builder.rsに対応するVM側の実装 - * previous_blockを追跡してPhi nodeの正しい値を選択 + * VM Loop/Phi Utilities + * + * Purpose: Track loop transitions and assist phi node resolution + * Responsibilities: PhiHandler/LoopExecutorでprevious_block・ループイテレーションを管理 + * Key APIs: LoopExecutor::{new,record_transition,execute_phi} + * Typical Callers: VM 実行ループ(ブロック遷移/phi評価) */ use super::vm::{VMValue, VMError}; @@ -211,4 +213,4 @@ mod tests { ); assert_eq!(result.unwrap(), VMValue::Integer(10)); } -} \ No newline at end of file +} diff --git a/src/backend/vm_values.rs b/src/backend/vm_values.rs index 9fb5300f..8b232bcb 100644 --- a/src/backend/vm_values.rs +++ b/src/backend/vm_values.rs @@ -1,5 +1,10 @@ /*! - * VM Value Operations - arithmetic, logical, and comparison helpers + * VM Value Operations + * + * Purpose: Arithmetic/logical/comparison helpers and boolean coercions + * Responsibilities: execute_binary_op / execute_unary_op / execute_compare_op + * Key APIs: execute_binary_op, execute_unary_op, execute_compare_op + * Typical Callers: vm_instructions::{execute_binop, execute_unaryop, execute_compare} */ use crate::mir::{BinaryOp, CompareOp, UnaryOp}; @@ -138,4 +143,3 @@ impl VM { } } } -