Files

nyash-codex 8fd3a2b509 docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)

2025-10-31 18:00:10 +09:00

38 KiB

Raw Blame History

Selfhost 綺麗綺麗計画 - Hakorune本流化ロードマップ

Phase 31.3: Selfhost Cleanup - Rust Learnings Application 作成日: 2025-10-19 想定期間: 8-10週間目標: Rustリファクタリング知見をSelfhostに適用し、Hakorune本流化を完成させる

1. 現状分析

Selfhost Compiler（selfhost/compiler/pipeline_v2/）

実装済み機能:

✅ 基本MIR生成（const, binop, compare, ret）
✅ 制御フロー（if/match）
✅ 関数呼び出し（call/method/newbox）
✅ SSA形式（local_ssa_box.hako, 187行）
✅ Using/名前空間解決（using_resolver_box.hako, 249行）
✅ 署名検証（signature_verifier_box.hako, 117行）
✅ JSON MIR出力

未実装機能:

❌ loopform命令の生成（最重要！）
❌ ループ専用PHI生成（Header/Latch/Exit PHI）
❌ トレース出力の統一化
❌ 状態管理の箱化

コード品質:

総行数: 3,007行（38ファイル）
最大ファイル: pipeline.hako（535行）⚠️ 巨大関数
平均ファイルサイズ: 79行
loop構文使用: 35箇所（12ファイル）
if文使用: 560箇所（31ファイル）

リファクタリング候補:

P0: pipeline.hako（535行）→ 3-4ファイルに分割
P0: using_resolver_box.hako（249行）→ 状態箱化
P1: stage1_extract_flow.hako（209行）→ フロー処理の箱化
P1: local_ssa_box.hako（187行）→ SSA処理の箱化

Selfhost VM（selfhost/hakorune-vm/）

実装済み命令: 22種類（16 MIR + 6 advanced = 138%カバレッジ！）

✅ barrier              ✅ binop               ✅ boxcall
✅ closure_call         ✅ compare             ✅ const
✅ constructor_call     ✅ copy                ✅ extern_call
✅ global_call          ✅ load                ✅ method_call
✅ mircall              ✅ module_function_call ✅ newbox
✅ nop                  ✅ phi                 ✅ safepoint
✅ store                ✅ terminator          ✅ typeop
✅ unaryop

未実装命令:

❌ loopform命令ハンドラ（最重要！）

コード品質:

総行数: 3,455行（67ファイル）
最大ファイル: closure_call_handler.hako（315行）
平均ファイルサイズ: 52行
テストファイル: 22個 ✅ 充実

リファクタリング候補:

P0: loopform_handler.hako実装（新規、150-200行想定）
P1: closure_call_handler.hako（315行）→ 小関数分割
P1: terminator_handler.hako（267行）→ Ret/Jump/Branch分離
P2: phi_handler.hako（234行）→ 単純化

既存の優れた設計:

✅ @match-based dispatch（instruction_dispatcher.hako, 72行）⭐参考にすべき
✅ Result-based error handling ⭐完璧
✅ 単一責務の原則（各ハンドラが独立）⭐Rust実装より優秀
✅ Block-based execution ⭐クリーン

2. Rust知見の適用可能性

LoopTraceBox → TraceBox (Hakorune版)

適用可能性: ⭐⭐⭐⭐⭐ 高（最優先）

Rust実装の知見:

// src/mir/loop_builder/trace.rs
pub struct LoopTraceBox {
    enabled: bool,
    prefix: String,
}

impl LoopTraceBox {
    pub fn log(&self, message: &str) {
        if self.enabled {
            eprintln!("{}{}", self.prefix, message);
        }
    }
}

Hakorune版実装方針:

// selfhost/shared/trace/trace_box.hako
static box TraceBox {
  enabled: IntegerBox
  prefix: StringBox

  birth(enabled, prefix) {
    me.enabled = enabled
    me.prefix = prefix
  }

  log(message) {
    if me.enabled == 1 {
      print(me.prefix + message)
    }
  }

  log_if(condition, message) {
    if me.enabled == 1 && condition == 1 {
      print(me.prefix + message)
    }
  }
}

期待効果:

✅ トレース出力の統一化（Compiler + VM）
✅ デバッグの効率化（環境変数で制御）
✅ 保守性向上（トレース追加が容易）
✅ 行数削減: ±0行（新規実装、既存の print() を置換）

実装優先度: P0（Week 1）

PhiBuilderBox → PhiEmitBox (Hakorune版)

適用可能性: ⭐⭐⭐⭐⭐ 高（最重要！）

Rust実装の知見:

// src/mir/phi_core/loop_phi.rs
pub struct LoopPhiBuilder<'a> {
    loop_ctx: &'a LoopContextBox,
    phi_registry: HashMap<String, ValueId>,
}

impl<'a> LoopPhiBuilder<'a> {
    // 3層PHI生成
    pub fn build_header_phi(&mut self, var_name: &str, init: ValueId, update: ValueId) -> ValueId
    pub fn build_latch_phi(&mut self, var_name: &str, ...) -> ValueId
    pub fn build_exit_phi(&mut self, var_name: &str, ...) -> ValueId
}

Hakorune版実装方針:

// selfhost/compiler/pipeline_v2/phi_emit_box.hako (新規)
static box PhiEmitBox {
  trace: TraceBox

  birth() {
    me.trace = new TraceBox(0, "[PhiEmit] ")
  }

  // Header PHI: ループ変数の初期化・更新
  emit_header_phi(var_name, init_reg, update_reg, entry_bb, latch_bb) {
    local phi_json = "{\"op\":\"phi\",\"dst\":" + me._next_reg() + ","
    phi_json = phi_json + "\"incoming\":[[" + init_reg + "," + entry_bb + "],"
    phi_json = phi_json + "[" + update_reg + "," + latch_bb + "]]}"

    me.trace.log("Header PHI: " + var_name + " = phi [" + init_reg + ", " + update_reg + "]")
    return phi_json
  }

  // Latch PHI: continue/fallthrough集約
  emit_latch_phi(var_name, continue_regs, continue_bbs) {
    // 複数経路からのcontinue集約
    local incoming = new ArrayBox()
    local i = 0
    loop(i < continue_regs.size()) {
      incoming.push("[" + continue_regs.get(i) + "," + continue_bbs.get(i) + "]")
      i = i + 1
    }

    local phi_json = "{\"op\":\"phi\",\"dst\":" + me._next_reg() + ","
    phi_json = phi_json + "\"incoming\":[" + incoming.join(",") + "]}"

    me.trace.log("Latch PHI: " + var_name + " (continue集約)")
    return phi_json
  }

  // Exit PHI: break時点の値統一
  emit_exit_phi(var_name, break_regs, break_bbs) {
    // 複数経路からのbreak集約
    local incoming = new ArrayBox()
    local i = 0
    loop(i < break_regs.size()) {
      incoming.push("[" + break_regs.get(i) + "," + break_bbs.get(i) + "]")
      i = i + 1
    }

    local phi_json = "{\"op\":\"phi\",\"dst\":" + me._next_reg() + ","
    phi_json = phi_json + "\"incoming\":[" + incoming.join(",") + "]}"

    me.trace.log("Exit PHI: " + var_name + " (break集約)")
    return phi_json
  }
}

期待効果:

✅ ループPHI生成の統一化（3層構造）
✅ Rust MIR vs Hakorune MIR のパリティ達成
✅ break/continue完全サポート
✅ 行数削減: +150-200行（新機能）

実装優先度: P0（Week 3-4）

LoopContextBox → LoopStateBox (Hakorune版)

適用可能性: ⭐⭐⭐⭐ 高

Rust実装の知見:

// src/mir/loop_builder/loop_context_box.rs
pub struct LoopContextBox {
    pub loop_header: BasicBlockId,
    pub loop_body: BasicBlockId,
    pub loop_latch: BasicBlockId,
    pub loop_exit: BasicBlockId,
    pub break_stack: Vec<BasicBlockId>,
    pub continue_stack: Vec<BasicBlockId>,
}

Hakorune版実装方針:

// selfhost/compiler/pipeline_v2/loop_state_box.hako (新規)
box LoopStateBox {
  loop_header: IntegerBox
  loop_body: IntegerBox
  loop_latch: IntegerBox
  loop_exit: IntegerBox
  break_stack: ArrayBox
  continue_stack: ArrayBox
  trace: TraceBox

  birth() {
    me.loop_header = -1
    me.loop_body = -1
    me.loop_latch = -1
    me.loop_exit = -1
    me.break_stack = new ArrayBox()
    me.continue_stack = new ArrayBox()
    me.trace = new TraceBox(0, "[LoopState] ")
  }

  set_blocks(header, body, latch, exit) {
    me.loop_header = header
    me.loop_body = body
    me.loop_latch = latch
    me.loop_exit = exit

    me.trace.log("Blocks: header=" + header + " body=" + body + " latch=" + latch + " exit=" + exit)
  }

  push_break(bb) {
    me.break_stack.push(bb)
    me.trace.log("Push break: bb=" + bb)
  }

  push_continue(bb) {
    me.continue_stack.push(bb)
    me.trace.log("Push continue: bb=" + bb)
  }

  get_break_count() {
    return me.break_stack.size()
  }

  get_continue_count() {
    return me.continue_stack.size()
  }
}

期待効果:

✅ ループ状態管理の一元化
✅ break/continueスタックの明示化
✅ 可読性・保守性向上
✅ 行数削減: +80-100行（新機能）、-50行（既存分散状態削除）

実装優先度: P1（Week 4）

巨大関数分割 → オーケストレーション層

適用可能性: ⭐⭐⭐⭐⭐ 高（最優先）

Rust実装の知見:

// 巨大関数（184行）を128行に削減
// 方針: 抽出・命名・オーケストレーション
pub fn build_loop_with_loopform(...) -> Result<ValueId, String> {
    // 1. セットアップ（10行）
    let loop_ctx = self.setup_loop_context()?;

    // 2. 条件評価（5行）
    let cond_value = self.evaluate_condition(&condition, &loop_ctx)?;

    // 3. ボディ実行（5行）
    self.execute_body(&body, &loop_ctx)?;

    // 4. PHI生成（5行）
    self.generate_loop_phis(&loop_ctx)?;

    // 5. クリーンアップ（3行）
    self.cleanup_loop(&loop_ctx)?;

    Ok(result)
}

// 各ステップは別関数（30-50行）
fn setup_loop_context(...) -> Result<LoopContextBox, String> { ... }
fn evaluate_condition(...) -> Result<ValueId, String> { ... }
fn execute_body(...) -> Result<(), String> { ... }
fn generate_loop_phis(...) -> Result<(), String> { ... }

Hakorune版実装方針:

// pipeline.hako（535行）を分割
// → pipeline_orchestrator.hako（150行）
// → pipeline_stage1_box.hako（100行）
// → pipeline_stage2_box.hako（100行）
// → pipeline_helpers_box.hako（既存、拡張）

// pipeline_orchestrator.hako (新規)
static box PipelineOrchestrator {
  trace: TraceBox

  birth() {
    me.trace = new TraceBox(0, "[Pipeline] ")
  }

  // オーケストレーション層（メインエントリーポイント）
  lower_stage1_to_mir(ast_json, prefer_cfg, trace_flag) {
    me.trace = new TraceBox(trace_flag, "[Pipeline] ")
    me.trace.log("Start: prefer_cfg=" + prefer_cfg)

    // 1. Stage 1: AST → Flow extraction
    local flow = PipelineStage1Box.extract_flow(ast_json, me.trace)
    if flow == null { return null }

    // 2. Stage 2: Flow → MIR generation
    local mir = PipelineStage2Box.generate_mir(flow, prefer_cfg, me.trace)
    if mir == null { return null }

    // 3. Finalize
    me.trace.log("Complete")
    return mir
  }
}

期待効果:

✅ 最大関数サイズ: 535行 → 150行以下
✅ 単一責務の原則の徹底
✅ テスト容易性の向上（各ステージを独立テスト）
✅ 行数削減: +250行（新ファイル）、-50行（重複削除）= +200行

実装優先度: P1（Week 6）

Legacy削除 → 単一経路化

適用可能性: ⭐⭐⭐ 中

Rust実装の知見:

// Legacy経路削除後（Phase 31.2）
pub fn build_loop(...) -> Result<ValueId, String> {
    // LoopFormBox 経路のみ（単一経路）
    self.build_loop_with_loopform(condition, body)
}

Hakorune版実装方針: Selfhostにはlegacy経路がほぼ存在しない（最初からloopform未実装）。今回の実装で最初からloopform経路のみを作成する。

期待効果:

✅ 単一経路化（legacy経路が存在しない状態を維持）
✅ 未使用コード削除（他の部分で数十行削減可能）
✅ 行数削減: -50〜-100行（未使用コード削除）

実装優先度: P2（Week 8）

3. 綺麗綺麗計画（8-10週間）

Phase 1: 基盤整備（Week 1-2）

Week 1: 現状分析 + トレース統一化

目的: コード品質のベースライン確立

実装内容:

Compiler全ファイルのコード品質分析（関数サイズ、責務分離）
- 最大関数サイズランキング作成
- 責務分離違反の特定
- 重複コードの特定
VM全ファイルのコード品質分析
- ハンドラのコード品質評価
- テストカバレッジ確認
TraceBox実装（新規）
- selfhost/shared/trace/trace_box.hako（50行）
- birth(enabled, prefix), log(message), log_if(condition, message)
- 環境変数制御（HAKO_TRACE=1）
Compiler/VMの既存print()をTraceBox.log()に置換（5-10箇所）
ドキュメント作成: SELFHOST_QUALITY_REPORT.md

成果物:

TraceBox実装（50行）
コード品質レポート（SELFHOST_QUALITY_REPORT.md）
トレース出力の統一API

削減見込み: +50行（TraceBox新規）

テスト:

# トレース有効化
HAKO_TRACE=1 ./target/release/hakorune apps/selfhost-compiler/main.hako

# 出力例:
# [Pipeline] Start: prefer_cfg=1
# [PhiEmit] Header PHI: i = phi [0, 10]
# [LoopState] Blocks: header=1 body=2 latch=3 exit=4

成功基準:

✅ TraceBox実装完了
✅ 既存のprint()を5箇所以上置換
✅ コード品質レポート作成完了

Week 2: 箱化パターン確立

目的: Hakorune版箱化設計の確立

実装内容:

箱化設計ドキュメント作成: SELFHOST_BOX_PATTERNS.md
- 状態管理箱（LoopStateBox, CompilerStateBox）
- ユーティリティ箱（TraceBox, PhiEmitBox）
- ハンドラ箱（既存のVM実装を参考）
サンプル実装:
- CompilerConfigBox（新規、30行）: prefer_cfg, trace等の設定
- LoopStateBox（新規、80行）: ループ状態管理
既存のVM命令ハンドラの箱化検証
- instruction_dispatcher.hakoの@match-based dispatchを参考にすべきパターンとして記録
- Result-based error handlingのベストプラクティス化

成果物:

Hakorune箱化パターンガイド（SELFHOST_BOX_PATTERNS.md）
CompilerConfigBox実装（30行）
LoopStateBox実装（80行）

削減見込み: +110行（新機能）

成功基準:

✅ 箱化パターンガイド作成完了
✅ 2つのサンプル箱実装完了
✅ @match-based dispatchのベストプラクティス文書化

Phase 2: loopform実装（Week 3-5）

Week 3: VM - loopform命令ハンドラ実装

目的: Hakorune VMでloop実行を可能に

実装内容:

loopform_handler.hako実装（新規、150-200行）
- Rust実装を参考: src/backend/mir_interpreter/handlers/flow.rs
- ループ制御フロー処理（header/body/latch/exit）
- PHI評価ロジック（Header PHI更新）
- break/continue処理
ループコンテキスト管理
- 現在のループ状態をスタックで管理（ネストループ対応）
- break/continueの適切なジャンプ先決定
エラーハンドリング
- 無限ループ検出（最大反復回数制御）
- 不正なbreak/continueの検出

instruction_dispatcher.hakoにloopform追加

"loopform" => LoopFormHandlerBox.handle(inst_json, regs, mem)

成果物:

loopform_handler.hako（新規、150-200行）
instruction_dispatcher.hako（+1行）
テストケース（5-10個）
- 単純ループ（0-9のカウント）
- break付きループ
- continue付きループ
- ネストループ
- ループ内変数更新

削減見込み: +150-200行（新機能）

テスト:

# loopform MIR JSON実行
./target/release/hakorune test_loopform_simple.hako
# 期待出力: 0, 1, 2, ..., 9

./target/release/hakorune test_loopform_break.hako
# 期待出力: 0, 1, 2, 3, 4 (5でbreak)

成功基準:

✅ loopform_handler.hako実装完了
✅ 5つのテストケース全PASS
✅ Rust VMとの挙動一致確認

Week 4: Compiler - loop構文MIR生成

目的: loop構文をloopform命令に変換

実装内容:

loop_emit_box.hako実装（新規、200-250行）

Rust実装を参考: src/mir/loop_builder/build.rs
loop構文パーサー: loop(condition) { body }

LoopFormBox命令生成:

{
  "op": "loopform",
  "dst": 5,
  "header": 1,
  "body": 2,
  "latch": 3,
  "exit": 4,
  "condition": {"bb": 1, "reg": 2},
  "body_blocks": [2],
  "latch_blocks": [3],
  "exit_blocks": [4]
}

phi_emit_box.hako実装（新規、150-200行）
- Rust PhiBuilderBoxを参考
- 3層PHI生成: Header PHI, Latch PHI, Exit PHI
- break/continue時のPHI更新
LoopStateBox統合（Week 2で実装済み）
- loop_emit_box.hakoでLoopStateBoxを使用
- ループ状態の一元管理
pipeline.hakoへの統合
- loop構文の検出・パース
- loop_emit_box.hakoの呼び出し

成果物:

loop_emit_box.hako（新規、200-250行）
phi_emit_box.hako（新規、150-200行）
pipeline.hako（+10-20行、loop構文統合）

削減見込み: +350-450行（新機能）

テスト:

# loop構文 → loopform MIR生成
cat > test_loop_simple.hako << 'EOF'
static box Main {
  main() {
    local i = 0
    loop(i < 10) {
      print(i)
      i = i + 1
    }
    return 0
  }
}
EOF

# MIR出力確認
./target/release/hakorune --dump-mir test_loop_simple.hako
# 期待: loopform命令生成、3層PHI確認

成功基準:

✅ loop_emit_box.hako実装完了
✅ phi_emit_box.hako実装完了
✅ loop構文 → loopform MIR生成確認
✅ 3層PHI生成確認

Week 5: loop統合テスト + Golden Test

目的: Rust MIR vs Hakorune MIR の一致確認

実装内容:

loop統合テスト（10-15ケース）
- 単純ループ（0-N）
- break付きループ（条件分岐）
- continue付きループ
- ネストループ（2重、3重）
- ループ内変数更新（複数変数）
- ループ後の変数参照（Exit PHI確認）
Golden Testフレームワーク実装
- tools/golden_test.sh（新規）
- Rust MIR出力とHakorune MIR出力の比較
- 差分検出・レポート生成
PHI処理のパリティ確認
- Header PHI: ループ変数の初期化・更新
- Latch PHI: continue/fallthrough集約
- Exit PHI: break時点の値統一
不一致の原因調査・修正
- レジスタ番号のズレ → 正規化
- PHI incoming順序のズレ → ソート
- 不要なPHI生成 → 最適化

成果物:

loop統合テストスイート（10-15ケース、apps/tests/loop_*.hako）
Golden Testフレームワーク（tools/golden_test.sh、100-150行）
パリティレポート（LOOP_PARITY_REPORT.md）

削減見込み: +300行（テスト）、+150行（Golden Test）

テスト:

# Golden Test実行
bash tools/golden_test.sh apps/tests/loop_simple.hako

# 出力例:
# [Golden] Rust MIR: 15 blocks, 42 instructions
# [Golden] Hako MIR: 15 blocks, 42 instructions
# [Golden] PHI count: Rust=6, Hako=6
# [Golden] Result: MATCH ✅

# 全ループテスト実行
bash tools/run_loop_tests.sh
# 期待: 10-15 PASS

成功基準:

✅ 10-15ループテスト全PASS
✅ Golden Testフレームワーク完成
✅ Rust MIR vs Hakorune MIR パリティ達成（90%以上一致）

Phase 3: リファクタリング（Week 6-8）

Week 6: 巨大関数分割

目的: 単一責務の原則適用

実装内容:

Compiler: pipeline.hako分割（535行 → 150行以下）
- pipeline_orchestrator.hako（新規、150行）: メインエントリーポイント
- pipeline_stage1_box.hako（新規、100行）: AST → Flow extraction
- pipeline_stage2_box.hako（新規、100行）: Flow → MIR generation
- pipeline_helpers_box.hako（既存、拡張+50行）
- 削減: 535行 → 450行 = -85行（重複削除）
Compiler: using_resolver_box.hako分割（249行 → 150行以下）
- using_state_box.hako（新規、80行）: 状態管理
- using_lookup_box.hako（新規、100行）: 名前解決
- 削減: 249行 → 230行 = -19行
VM: closure_call_handler.hako分割（315行 → 200行以下）
- closure_params_extractor.hako（新規、50行）
- closure_captures_extractor.hako（新規、70行）
- 削減: 315行 → 270行 = -45行
VM: terminator_handler.hako分割（267行 → 150行以下）
- ret_handler.hako（新規、50行）
- jump_handler.hako（新規、40行）
- branch_handler.hako（新規、60行）
- 削減: 267行 → 217行 = -50行

成果物:

分割後のファイル群（8ファイル、計650行）
オーケストレーション層の明確化
最大関数サイズ: 150行以下

削減見込み: +650行（新ファイル）、-200行（重複削除）= +450行

テスト:

# 分割後の動作確認
tools/smokes/v2/run.sh --profile quick

# 期待: 全テストPASS（リファクタリング前後で同一結果）

成功基準:

✅ 最大関数サイズ: 150行以下達成
✅ 全スモークテストPASS
✅ コード重複削減: -200行

Week 7: 状態管理箱化

目的: 状態管理の一元化

実装内容:

CompilerStateBox実装（新規、100行）
- 現在のブロックID、レジスタカウンタ、変数マップ、SSA状態
- フィールド統合: 分散していた10-15個の状態を1箇所に集約
- birth(), set_block(), next_reg(), set_var(), get_var()
VMStateBox実装（新規、80行）
- レジスタマップ、メモリマップ、現在のブロックID、ループスタック
- フィールド統合: 分散していた5-8個の状態を1箇所に集約
- birth(), get_reg(), set_reg(), get_mem(), set_mem()
既存コードの状態管理箱化への移行
- Compiler: pipeline_*.hako（5-10ファイル）
- VM: hakorune_vm_core.hako, *_handler.hako（5-10ファイル）
状態遷移の可視化
- TraceBox統合（状態変化をログ出力）

成果物:

compiler_state_box.hako（新規、100行）
vm_state_box.hako（新規、80行）
状態管理の一元化（15-20箇所の状態参照を箱化）

削減見込み: +180行（新箱）、-50行（重複状態削除）= +130行

テスト:

# 状態管理のトレース確認
HAKO_TRACE=1 ./target/release/hakorune apps/tests/loop_simple.hako

# 出力例:
# [CompilerState] Block: 0 → 1
# [CompilerState] Reg: v%1 → v%2
# [VMState] Reg[v%1] = 42
# [VMState] Mem[global_0] = 100

成功基準:

✅ CompilerStateBox実装完了
✅ VMStateBox実装完了
✅ 状態管理の一元化（15-20箇所移行）
✅ 状態遷移のトレース可視化

Week 8: 単一経路化 + Legacy削除

目的: 複雑な分岐の削除

実装内容:

未使用コード削除
- Compiler: 未使用のヘルパー関数、重複ユーティリティ（20-30箇所）
- VM: 未使用の実験的ハンドラ、デバッグコード（10-15箇所）
- コメントアウトされたコード削除
重複ロジック統一化
- JSON解析の重複パターン → JsonCursorBox統一
- 文字列操作の重複 → StringHelpers統一
- エラーハンドリングの重複 → Result統一
単一経路化
- loopform経路のみに統一（legacy経路なし）
- if/match の不要な分岐削除
- 実験的機能の削除（使用されていないもの）

成果物:

クリーンなコードベース
未使用コード削除リスト（UNUSED_CODE_REMOVED.md）

削減見込み: -100〜-200行

テスト:

# クリーンアップ後の動作確認
tools/smokes/v2/run.sh --profile quick
tools/smokes/v2/run.sh --profile integration

# 期待: 全テストPASS

成功基準:

✅ 未使用コード削除: -100行以上
✅ 全スモークテストPASS
✅ 未使用コード削除リスト作成

Phase 4: Golden Testing + ドキュメント（Week 9-10）

Week 9: 包括的Golden Test

目的: Rust vs Hakorune の完全パリティ

実装内容:

すべてのMIR命令のGolden Test（50-100ケース）
- 基本命令: const, binop, compare, ret, nop
- 制御フロー: jump, branch, phi, loopform
- メモリ操作: load, store
- オブジェクト操作: newbox, boxcall
- 関数呼び出し: mir_call（4種類）, extern_call
制御フローの包括的テスト
- if/else（単純、ネスト、チェーン）
- match（単純、多分岐、ネスト）
- loop（単純、break、continue、ネスト）
- 複合制御フロー（if + loop, match + loop等）
PHI処理の完全一致確認
- if/else PHI（2経路）
- match PHI（N経路）
- loop Header PHI（init/update）
- loop Latch PHI（continue集約）
- loop Exit PHI（break集約）
パリティ未達成箇所の修正
- レジスタ番号正規化
- PHI incoming順序ソート
- 不要なPHI削除
- MIR最適化のパリティ確認

成果物:

包括的Golden Testスイート（50-100ケース、apps/tests/golden_*.hako）
パリティ達成レポート（GOLDEN_TEST_REPORT.md）
未達成箇所リスト・修正履歴

削減見込み: +500-1000行（テスト）

テスト:

# Golden Test全実行
bash tools/golden_test_suite.sh

# 出力例:
# [Golden] Test 1/100: loop_simple.hako ... MATCH ✅
# [Golden] Test 2/100: if_nested.hako ... MATCH ✅
# ...
# [Golden] Test 100/100: complex_control.hako ... MATCH ✅
#
# [Golden] Summary: 100/100 PASS (100% パリティ達成)

成功基準:

✅ 50-100 Golden Testケース作成
✅ パリティ達成率: 95%以上
✅ 未達成箇所の修正完了

Week 10: ドキュメント整備

目的: Selfhost本流化の完成

実装内容:

Selfhost実装ガイド更新
- docs/development/selfhost/IMPLEMENTATION_GUIDE.md（新規、1000-1500行）
- アーキテクチャ概要
- Compiler実装詳細（pipeline, loop, phi等）
- VM実装詳細（ハンドラ、制御フロー等）
- トレース・デバッグ方法
- 箱化パターン
Rust vs Hakorune対応表作成
- docs/development/selfhost/RUST_HAKORUNE_MAPPING.md（新規、500-800行）
- MIR命令対応表（Rust → Hakorune）
- 箱化パターン対応表（LoopTraceBox → TraceBox等）
- 関数対応表（build_loop → loop_emit_box等）
- アーキテクチャ対応（module構造 → using構造）
綺麗綺麗完了レポート作成
- docs/private/roadmap/phases/phase-31.3/CLEANUP_REPORT.md（新規、800-1200行）
- 実施内容サマリー
- 削減/追加行数の詳細
- 品質改善の定量評価
- パリティ達成率
- 今後の課題
READMEの更新
- selfhost/README.md（既存、更新+200-300行）
- セットアップ方法
- ビルド方法
- テスト実行方法
- トラブルシューティング

成果物:

IMPLEMENTATION_GUIDE.md（新規、1000-1500行）
RUST_HAKORUNE_MAPPING.md（新規、500-800行）
CLEANUP_REPORT.md（新規、800-1200行）
selfhost/README.md（更新、+200-300行）

削減見込み: ±0行（ドキュメント）

成功基準:

✅ 4つのドキュメント作成完了
✅ 新規開発者が30分以内にSelfhost実装を理解可能
✅ Rust開発者がHakorune実装に即座に対応可能

4. 優先順位マトリクス

P0（最優先） - Selfhost本流化の必須要素

優先度	タスク	週	期待効果	削減/追加行数
P0-1	loopform VM実装	Week 3	ループ実行可能に	+150-200行
P0-2	loop/phi Compiler実装	Week 4	loop構文→MIR生成	+350-450行
P0-3	Golden Test	Week 5,9	パリティ達成	+800-1300行
P0-4	TraceBox統一化	Week 1	デバッグ効率化	+50行

P0合計: +1350-2000行（新機能）

P1（重要） - コード品質向上

優先度	タスク	週	期待効果	削減/追加行数
P1-1	状態管理箱化	Week 7	状態管理一元化	+130行
P1-2	巨大関数分割	Week 6	可読性向上	+450行
P1-3	箱化パターン確立	Week 2	設計品質向上	+110行

P1合計: +690行（品質向上）

P2（改善） - 長期的な保守性

優先度	タスク	週	期待効果	削減/追加行数
P2-1	Legacy削除	Week 8	コード削減	-100〜-200行
P2-2	ドキュメント整備	Week 10	保守性向上	±0行

P2合計: -100〜-200行（削減）

総合見込み

項目	行数変化
新機能実装	+1350-2000行（loopform, Golden Test等）
品質向上	+690行（状態箱化、関数分割等）
削減	-100〜-200行（未使用コード削除）
ドキュメント	+2500-3800行（ガイド、対応表等）
総計（コード）	+1940-2490行
総計（含ドキュメント）	+4440-6290行

コメント: 行数増加は「新機能実装」（loopform, PHI, Golden Test）が主因。既存機能はリファクタリングで改善しつつ、大幅な削減はない。

5. 成功基準

定量基準

loopform実装完了（VM + Compiler）
- VM: loopform_handler.hako実装済み
- Compiler: loop_emit_box.hako + phi_emit_box.hako実装済み
- テスト: 5-10ケース全PASS
Golden Test 50+ケース全PASS
- Rust MIR vs Hakorune MIR パリティ達成率: 95%以上
- すべてのMIR命令カバー
- 制御フロー完全カバー
最大関数サイズ: 150行以下（Hakorune版）
- Compiler: pipeline.hako（535行 → 150行以下）
- VM: closure_call_handler.hako（315行 → 200行以下）
コード削減: -100行以上（Legacy削除）
- 未使用コード削除
- 重複ロジック統一化

定性基準

Selfhost単体でloop実行可能
- loop構文 → loopform MIR → VM実行
- break/continue完全サポート
- ネストループサポート
Rust MIR vs Hakorune MIR 完全パリティ
- すべてのMIR命令で一致
- PHI処理（3層）で一致
- 制御フローで一致
コードの可読性・保守性向上
- 単一責務の原則徹底
- 箱化パターン確立
- トレース出力統一化
- 状態管理一元化
新規開発者が30分以内に理解可能
- IMPLEMENTATION_GUIDE.md完備
- RUST_HAKORUNE_MAPPING.md完備
- サンプルコード充実

6. リスク管理

リスク1: loopform実装の複雑性

確率: ⭐⭐⭐ 中影響: ⭐⭐⭐⭐⭐ 高説明: loopform命令の実装は複雑で、Rust実装の理解・移植に時間がかかる可能性

軽減策:

✅ Rust実装を参考にする（今回のリファクタリング後のクリーンな実装）
✅ 段階的実装（VM → Compiler → Golden Test）
✅ 週次レビュー（Week 3, 4, 5で進捗確認）
✅ トレース出力の充実（デバッグ容易性向上）

リスク2: Hakorune構文の制約

確率: ⭐⭐⭐ 中影響: ⭐⭐⭐ 中説明: Hakorune構文の制約（Option/Result未実装、ジェネリクス未実装等）により、Rust実装の直接移植が困難

軽減策:

✅ Rust実装の複雑なパターンを避ける（シンプル化）
✅ Hakorune向けに簡略化した設計（箱化で対応）
✅ ドキュメント化（制約事項を明記）
✅ 箱化パターン確立（Week 2）

リスク3: パリティ未達成

確率: ⭐⭐ 低影響: ⭐⭐⭐⭐⭐ 高説明: Rust MIR vs Hakorune MIR のパリティが95%未満で、本流化が困難

軽減策:

✅ Golden Testフレームワークの早期構築（Week 5）
✅ 継続的なパリティ確認（Week 5, 9）
✅ 差分が出た場合の調査プロセス確立
✅ 正規化・ソートによる差分吸収

リスク4: スコープクリープ

確率: ⭐⭐⭐⭐ 高影響: ⭐⭐⭐ 中説明: リファクタリング中に追加機能の実装を始めてしまい、計画遅延

軽減策:

✅ 80/20ルールの徹底（完璧より進捗）
✅ 追加機能は docs/development/proposals/ideas/ に記録
✅ 週次レビューで進捗確認
✅ マイルストーンの厳守

7. マイルストーン

Week	マイルストーン	成功基準	削減/追加行数
2	基盤整備完了	TraceBox実装、箱化パターン確立	+160行
5	loopform実装完了	VM実行可能、Golden Test基礎	+800-1100行
8	リファクタリング完了	最大関数150行以下、状態箱化	+580行、-100〜-200行
10	Selfhost本流化完成	Golden Test全PASS、ドキュメント完備	+3300-4800行

総計: +4440-6290行（コード +1940-2490行、ドキュメント +2500-3800行）

8. 長期ビジョン（Phase 15.76/15.77連携）

Phase 15.76: extern_c戦略

タイムライン: Selfhost綺麗綺麗完了後、4週間目標: C ABI経由でLLVMバックエンド連携

実装内容:

Selfhost実装が完成後、C ABI経由でLLVMバックエンド連携
Hakoruneコンパイラ → MIR JSON → LLVM (C ABI)
extern_c構文実装: Hakorune から C関数直接呼び出し

Selfhostへの影響:

Selfhost Compiler が MIR JSON を生成（既に実装済み）
LLVM Backend（Rust実装）が C ABI で .o ファイル生成
連携層の実装（C ABI bridge）

Phase 15.77: 凍結EXE確定

タイムライン: Phase 15.76完了後、6週間目標: Rust層最小化、Hakorune本流化

実装内容:

hako-frozen-v1.exe: Rust実装を凍結
- Parser + MIR Builder + VM実行エンジンを含む
- タグ付け・配布（Git tag, GitHub Release）
Selfhost = 主要開発: Hakoruneスクリプト版が本流
- すべての開発はSelfhostで実施
- Rust層は凍結（バグ修正のみ）
Rust層最小化: 99.8%削減（VM実行エンジンのみ）
- 99,406行 → 100-200行（VM実行エンジンのみ残す）
- Parser削除（~40,000行削減）
- MIR Builder削除（~40,000行削減）

Selfhostへの影響:

Selfhost Compiler が「唯一のパーサー・MIRビルダー」に
Rust層はVMエンジンのみ（凍結）
開発速度の向上（Hakoruneスクリプトのみメンテナンス）

タイムライン総合:

Selfhost綺麗綺麗: 10週間（本計画）
Phase 15.76実装: 4週間（extern_c戦略）
Phase 15.77実装: 6週間（凍結EXE作成）
合計: 20週間（約5ヶ月）

9. 次のステップ

即座に開始可能

1. Week 1: 現状分析 + トレース統一化

# コード品質分析
bash -c 'for file in selfhost/compiler/pipeline_v2/*.hako; do \
  lines=$(wc -l < "$file"); \
  name=$(basename "$file"); \
  echo "$lines $name"; \
done | sort -rn > QUALITY_ANALYSIS_COMPILER.txt'

bash -c 'for file in selfhost/hakorune-vm/*.hako; do \
  lines=$(wc -l < "$file"); \
  name=$(basename "$file"); \
  echo "$lines $name"; \
done | sort -rn > QUALITY_ANALYSIS_VM.txt'

# TraceBox実装
mkdir -p selfhost/shared/trace
# → trace_box.hako実装（50行）

準備が必要

2. loopform設計レビュー（Week 3開始前）

実施内容:

Rust実装の詳細確認: src/mir/loop_builder/build.rs, src/backend/mir_interpreter/handlers/flow.rs
Hakorune版設計案作成: loopform_handler.hako, loop_emit_box.hako
レビュー会議（オンライン or ドキュメント）

成果物:

loopform設計書（LOOPFORM_DESIGN.md, 500-800行）
実装チェックリスト

継続的実施

3. 週次進捗レビュー

実施内容:

毎週の成果確認（マイルストーン達成率）
リスク早期発見（遅延、パリティ未達成等）
計画調整（必要に応じてスコープ縮小）

レビュー形式:

ドキュメントベース: WEEKLY_PROGRESS_Wxx.md（各週作成）
記録項目:
- 実施内容
- 成果物
- 削減/追加行数
- 問題点・リスク
- 次週の計画

10. まとめ

Selfhost綺麗綺麗計画: 10週間で本流化を達成

核心目標:

✅ loopform完全実装（VM + Compiler + Golden Test）
✅ Rust知見の適用（箱化、統一化、単一責務）
✅ コード品質向上（可読性、保守性、拡張性）
✅ Selfhost = 本流の体制確立

期待効果

機能面:

✅ Selfhost単体でloop実行可能
✅ break/continue完全サポート
✅ ネストループサポート
✅ Rust MIR vs Hakorune MIR 完全パリティ（95%以上）

品質面:

✅ 最大関数サイズ: 150行以下
✅ 単一責務の原則徹底
✅ トレース出力統一化
✅ 状態管理一元化
✅ 箱化パターン確立

保守面:

✅ 新規開発者が30分以内に理解可能
✅ Rust開発者がHakorune実装に即座に対応可能
✅ ドキュメント完備（実装ガイド、対応表等）

戦略面:

✅ Hakoruneスクリプト版が主要実装に
✅ Rust層の最小化（Phase 15.77へ）
✅ 世界レベルの保守性・可読性達成

今回のRustリファクタリングの価値

1. クリーンな参考実装:

LoopFormBox 経路のみの単純な構造
128行の build_loop_with_loopform（リファクタリング後）
3層PHI生成の明確な実装

2. 箱化パターンの確立:

LoopTraceBox（トレース統一化）
LoopContextBox（状態管理）
PhiBuilderBox（PHI生成）

3. Golden Testの重要性認識:

Rust MIR vs Hakorune MIR のパリティが最重要
継続的な検証フレームワークの必要性

4. オーケストレーション層の設計:

巨大関数を小関数に分割
各ステップを明確に命名
テスト容易性の向上

Selfhostが輝く未来へ！

2025年末: Selfhost本流化完成

Hakoruneスクリプト版が主要実装
Rust層は凍結（hako-frozen-v1.exe）
開発速度の向上（Hakoruneのみメンテナンス）

2026年: 凍結EXE確定

Rust層最小化（99.8%削減）
単一パーサ体制（Hakoruneパーサーのみ開発）
世界レベルの保守性・可読性

Hakorune本流化 - 世界に誇るセルフホストシステムへ！ 🚀

このドキュメント: docs/private/roadmap/phases/phase-31.3/SELFHOST_CLEANUP_PLAN.md

38 KiB Raw Blame History Unescape Escape

Selfhost 綺麗綺麗計画 - Hakorune本流化ロードマップ

1. 現状分析

Selfhost Compiler（selfhost/compiler/pipeline_v2/）

Selfhost VM（selfhost/hakorune-vm/）

2. Rust知見の適用可能性

LoopTraceBox → TraceBox (Hakorune版)

PhiBuilderBox → PhiEmitBox (Hakorune版)

LoopContextBox → LoopStateBox (Hakorune版)

巨大関数分割 → オーケストレーション層

Legacy削除 → 単一経路化

3. 綺麗綺麗計画（8-10週間）

Phase 1: 基盤整備（Week 1-2）

Week 1: 現状分析 + トレース統一化

Week 2: 箱化パターン確立

Phase 2: loopform実装（Week 3-5）

Week 3: VM - loopform命令ハンドラ実装

Week 4: Compiler - loop構文MIR生成

Week 5: loop統合テスト + Golden Test

Phase 3: リファクタリング（Week 6-8）

Week 6: 巨大関数分割

Week 7: 状態管理箱化

Week 8: 単一経路化 + Legacy削除

Phase 4: Golden Testing + ドキュメント（Week 9-10）

Week 9: 包括的Golden Test

Week 10: ドキュメント整備

4. 優先順位マトリクス

P0（最優先） - Selfhost本流化の必須要素

P1（重要） - コード品質向上

P2（改善） - 長期的な保守性

総合見込み

5. 成功基準

定量基準

定性基準

6. リスク管理

リスク1: loopform実装の複雑性

リスク2: Hakorune構文の制約

リスク3: パリティ未達成

リスク4: スコープクリープ

7. マイルストーン

8. 長期ビジョン（Phase 15.76/15.77連携）

Phase 15.76: extern_c戦略

Phase 15.77: 凍結EXE確定

9. 次のステップ

即座に開始可能

準備が必要

継続的実施

10. まとめ

Selfhost綺麗綺麗計画: 10週間で本流化を達成

期待効果

今回のRustリファクタリングの価値

Selfhostが輝く未来へ！

38 KiB

Raw Blame History