11 KiB
11 KiB
Phase 31.3 Summary - エグゼクティブサマリー
Selfhost 綺麗綺麗計画: 10週間でHakorune本流化を達成
作成日: 2025-10-19 対象読者: プロジェクトオーナー、PM、アーキテクト
🎯 核心目標（30秒で理解）
Phase 31（Rustリファクタリング）で得た5つの知見をSelfhost（Hakoruneスクリプト版）に適用し、Hakorune本流化を完成させる
- ✅ loopform完全実装（VM + Compiler + Golden Test）
- ✅ Rust MIR vs Hakorune MIR 完全パリティ（95%以上）
- ✅ コード品質向上（最大関数150行以下、状態箱化、トレース統一化）
- ✅ ドキュメント整備（実装ガイド、対応表、レポート）
期間: 10週間（Phase 1-4） 削減/追加: +4,440-6,290行（コード +1,940-2,490行、ドキュメント +2,500-3,800行）
📊 現状（Phase 31.3開始前）
Selfhost Compiler（selfhost/compiler/pipeline_v2/）
- 総行数: 3,007行（38ファイル）
- 最大ファイル: pipeline.hako（535行）⚠️ 巨大関数
- 実装済み: 基本MIR生成、制御フロー（if/match）、SSA、Using/名前空間
- 未実装: loopform命令生成、ループ専用PHI、トレース統一化
Selfhost VM（selfhost/hakorune-vm/）
- 総行数: 3,455行（67ファイル）
- 実装済み命令: 22種類（16 MIR + 6 advanced = 138%カバレッジ！）
- 最大ファイル: closure_call_handler.hako（315行）
- 未実装: loopform命令ハンドラ
評価
- ✅ 基盤は完成（22命令ハンドラ、@match-based dispatch、Result-based error handling）
- ❌ loopform未実装（Compiler + VM）
- ❌ Rust MIR パリティ未達成（loop構文が動作しない）
- ⚠️ 巨大関数あり（pipeline.hako 535行、closure_call_handler.hako 315行）
🚀 Phase 31.3 の構成（10週間）
Phase 1: 基盤整備（Week 1-2）
目標: トレース統一化、箱化パターン確立
主要成果物:
- TraceBox実装（50行）⭐Rust LoopTraceBox移植
- CompilerConfigBox実装（30行）
- LoopStateBox実装（80行）
- コード品質レポート
削減/追加: +160行
Phase 2: loopform実装（Week 3-5）⭐最重要
目標: loop構文をloopform命令に変換、VM実行可能に
主要成果物:
- VM: loopform_handler.hako（150-200行）
- Compiler: loop_emit_box.hako（200-250行）+ phi_emit_box.hako（150-200行）
- Golden Test基礎: Golden Testフレームワーク（100-150行）
- テスト: 10-15ケース
削減/追加: +800-1,100行
実装詳細:
- Week 3: VM loopform実装（Rust
handlers/flow.rs参考） - Week 4: Compiler loop/phi実装（Rust
loop_builder/build.rs参考） - Week 5: Golden Test（Rust MIR vs Hakorune MIR 一致確認）
Phase 3: リファクタリング（Week 6-8）
目標: コード品質向上、保守性向上
主要成果物:
- 巨大関数分割:
- pipeline.hako（535行 → 150行以下）
- closure_call_handler.hako（315行 → 200行以下）
- 状態管理箱化:
- CompilerStateBox実装（100行）
- VMStateBox実装（80行）
- Legacy削除（-100〜-200行）
削減/追加: +580行、-100〜-200行
Phase 4: Golden Testing + ドキュメント（Week 9-10）
目標: Rust vs Hakorune 完全パリティ、ドキュメント整備
主要成果物:
- Golden Test: 50-100ケース全PASS（パリティ95%以上）
- IMPLEMENTATION_GUIDE.md（1,000-1,500行）
- RUST_HAKORUNE_MAPPING.md（500-800行）
- CLEANUP_REPORT.md（800-1,200行）
削減/追加: +3,300-4,800行（ドキュメント主体）
📈 Rust知見の適用（5つのパターン）
1. LoopTraceBox → TraceBox
適用可能性: ⭐⭐⭐⭐⭐ 高（P0）
- トレース出力の統一化（Compiler + VM）
- 環境変数制御（HAKO_TRACE=1）
- デバッグ効率化
2. PhiBuilderBox → PhiEmitBox ⭐最重要
適用可能性: ⭐⭐⭐⭐⭐ 高（P0）
- 3層PHI生成（Header/Latch/Exit）
- break/continue完全サポート
- Rust実装の直接移植
3. LoopContextBox → LoopStateBox
適用可能性: ⭐⭐⭐⭐ 高（P1）
- ループ状態管理の一元化
- break/continueスタックの明示化
4. 巨大関数分割 → オーケストレーション層
適用可能性: ⭐⭐⭐⭐⭐ 高（P1）
- pipeline.hako（535行 → 150行以下）
- 単一責務の原則徹底
- テスト容易性向上
5. Legacy削除 → 単一経路化
適用可能性: ⭐⭐⭐ 中（P2）
- loopform経路のみ（legacy経路なし）
- 未使用コード削除（-100〜-200行）
💰 ROI（投資対効果）
投資
- 時間: 10週間（約2.5ヶ月）
- 工数: 1人月 × 2.5ヶ月 = 2.5人月
- リスク: loopform実装の複雑性（中）、Hakorune構文の制約（中）
リターン
- 機能面:
- ✅ Selfhost単体でloop実行可能
- ✅ Rust MIR vs Hakorune MIR 完全パリティ（95%以上）
- 品質面:
- ✅ 最大関数サイズ: 150行以下
- ✅ 保守性・可読性の大幅向上
- 戦略面:
- ✅ Hakorune本流化（Phase 15.76/15.77への準備完了）
- ✅ Rust層最小化の準備（99.8%削減へ）
ROI評価: ⭐⭐⭐⭐⭐ 極めて高い
- Selfhost本流化の必須ステップ
- Phase 15.76/15.77への橋渡し
- 世界レベルの保守性・可読性達成
🎯 マイルストーン（4つの検問）
| Week | マイルストーン | 成功基準 | リスク |
|---|---|---|---|
| 2 | 基盤整備完了 | TraceBox実装、箱化パターン確立 | 低 |
| 5 | loopform実装完了 | VM実行可能、Golden Test基礎 | 高⚠️ |
| 8 | リファクタリング完了 | 最大関数150行以下、状態箱化 | 低 |
| 10 | Selfhost本流化完成 | Golden Test全PASS、ドキュメント完備 | 中 |
Critical Path: Week 3-5（loopform実装）⚠️ 最重要区間
🔥 リスク管理
リスク1: loopform実装の複雑性（Week 3-5）
確率: ⭐⭐⭐ 中 | 影響: ⭐⭐⭐⭐⭐ 高
軽減策:
- ✅ Rust実装（build.rs, 128行）を参考
- ✅ 段階的実装（VM → Compiler → Golden Test）
- ✅ 週次レビュー（早期問題発見）
リスク2: Hakorune構文の制約
確率: ⭐⭐⭐ 中 | 影響: ⭐⭐⭐ 中
軽減策:
- ✅ 簡略化設計（Rust実装の複雑なパターンを避ける）
- ✅ 箱化パターン確立（Week 2）
- ✅ ドキュメント化（制約事項を明記）
リスク3: パリティ未達成（Week 5, 9）
確率: ⭐⭐ 低 | 影響: ⭐⭐⭐⭐⭐ 高
軽減策:
- ✅ Golden Testフレームワーク早期構築（Week 5）
- ✅ 継続的なパリティ確認
- ✅ 正規化・ソートによる差分吸収
リスク4: スコープクリープ（全期間）
確率: ⭐⭐⭐⭐ 高 | 影響: ⭐⭐⭐ 中
軽減策:
- ✅ 80/20ルール徹底（完璧より進捗）
- ✅ 追加機能は
docs/development/proposals/ideas/に記録 - ✅ 週次レビューで進捗確認
🔗 長期ビジョン（Phase 15.76/15.77連携）
Phase 31.3完了後の展開
Phase 15.76: extern_c戦略（+4週間）
- C ABI経由でLLVMバックエンド連携
- extern_c構文実装
- AOT導線確立
Phase 15.77: 凍結EXE確定（+6週間）
- hako-frozen-v1.exe作成・配布
- Rust層最小化（99.8%削減: 99,406行 → 100-200行）
- Selfhost = 主要開発
合計タイムライン: 20週間（約5ヶ月）
- Phase 31.3: 10週間（本計画）
- Phase 15.76: 4週間
- Phase 15.77: 6週間
📋 即座に開始可能なアクション
Action 1: コード品質分析（15分）
cd /home/tomoaki/git/hakorune-selfhost
bash docs/private/roadmap/phases/phase-31.3/quick_quality_check.sh
Action 2: TraceBox実装（30分）
mkdir -p selfhost/shared/trace
# → trace_box.hako実装（QUICK_START.md参照）
Action 3: Week 1計画レビュー（10分）
cat docs/private/roadmap/phases/phase-31.3/QUICK_START.md
📚 ドキュメント構成（2,068行）
| ドキュメント | 行数 | サイズ | 対象読者 |
|---|---|---|---|
| SELFHOST_CLEANUP_PLAN.md | 1,250 | 39KB | PM/実装者 ⭐完全計画 |
| QUICK_START.md | 366 | 8.3KB | 実装者 ⭐即座実行 |
| README.md | 234 | 6.6KB | すべて ⭐概要 |
| INDEX.md | 218 | 7.9KB | すべて ⭐索引 |
| 合計 | 2,068 | 62KB | - |
🎯 決定が必要な事項
即座の決定（Week 1開始前）
- ✅ Phase 31.3の承認（10週間計画）
- ✅ Week 1開始のGO判断（TraceBox実装 + 品質分析）
- ✅ リソース確保（実装者1名 × 10週間）
計画中の決定（Week 3開始前）
- ⏳ loopform設計レビュー（Rust実装との差分確認）
- ⏳ Golden Test基準策定（パリティ95%は適切か？）
後回し可能（Week 6以降）
- 🔄 リファクタリングのスコープ調整（P1/P2の優先順位）
- 🔄 ドキュメントの詳細度調整（実装ガイドの粒度）
🚀 推奨アクション
Phase 31.3を承認して即座に開始すべき理由:
- ✅ Phase 31完了の直後が最適（知見が新鮮、Rust実装が参照可能）
- ✅ Selfhost本流化の必須ステップ（Phase 15.76/15.77への橋渡し）
- ✅ 投資対効果が極めて高い（2.5人月で世界レベルの保守性達成）
- ✅ リスクは管理可能（段階的実装、週次レビュー、80/20ルール）
- ✅ 基盤は完成済み（Hakorune VM 138%カバレッジ、@match-based dispatch完備）
次のステップ（今日中に実施可能）:
# 1. ドキュメント確認（15分）
cd /home/tomoaki/git/hakorune-selfhost
cat docs/private/roadmap/phases/phase-31.3/README.md
cat docs/private/roadmap/phases/phase-31.3/QUICK_START.md
# 2. コード品質分析（15分）
bash -c 'for file in selfhost/compiler/pipeline_v2/*.hako; do \
lines=$(wc -l < "$file"); name=$(basename "$file"); echo "$lines $name"; \
done | sort -rn' > docs/private/roadmap/phases/phase-31.3/QUALITY_ANALYSIS_COMPILER.txt
# 3. Week 1開始（TraceBox実装、30分）
mkdir -p selfhost/shared/trace
# → trace_box.hako実装
📞 問い合わせ
- 計画詳細: SELFHOST_CLEANUP_PLAN.md
- 即座実行: QUICK_START.md
- 索引: INDEX.md
Phase 31.3: Selfhost 綺麗綺麗計画 - 今すぐ始めましょう！ 🚀
Hakoruneが世界に誇るセルフホストシステムになる第一歩です。