326 lines
11 KiB
Markdown
326 lines
11 KiB
Markdown
# Phase 31.3 Summary - エグゼクティブサマリー
|
||
|
||
**Selfhost 綺麗綺麗計画: 10週間でHakorune本流化を達成**
|
||
|
||
作成日: 2025-10-19
|
||
対象読者: プロジェクトオーナー、PM、アーキテクト
|
||
|
||
---
|
||
|
||
## 🎯 核心目標（30秒で理解）
|
||
|
||
**Phase 31（Rustリファクタリング）で得た5つの知見をSelfhost（Hakoruneスクリプト版）に適用し、Hakorune本流化を完成させる**
|
||
|
||
1. ✅ **loopform完全実装**（VM + Compiler + Golden Test）
|
||
2. ✅ **Rust MIR vs Hakorune MIR 完全パリティ**（95%以上）
|
||
3. ✅ **コード品質向上**（最大関数150行以下、状態箱化、トレース統一化）
|
||
4. ✅ **ドキュメント整備**（実装ガイド、対応表、レポート）
|
||
|
||
**期間**: 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行
|
||
|
||
**実装詳細**:
|
||
1. Week 3: VM loopform実装（Rust `handlers/flow.rs` 参考）
|
||
2. Week 4: Compiler loop/phi実装（Rust `loop_builder/build.rs` 参考）
|
||
3. 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構文の制約（中）
|
||
|
||
### リターン
|
||
1. **機能面**:
|
||
- ✅ Selfhost単体でloop実行可能
|
||
- ✅ Rust MIR vs Hakorune MIR 完全パリティ（95%以上）
|
||
2. **品質面**:
|
||
- ✅ 最大関数サイズ: 150行以下
|
||
- ✅ 保守性・可読性の大幅向上
|
||
3. **戦略面**:
|
||
- ✅ 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分）
|
||
```bash
|
||
cd /home/tomoaki/git/hakorune-selfhost
|
||
bash docs/private/roadmap/phases/phase-31.3/quick_quality_check.sh
|
||
```
|
||
|
||
### Action 2: TraceBox実装（30分）
|
||
```bash
|
||
mkdir -p selfhost/shared/trace
|
||
# → trace_box.hako実装（QUICK_START.md参照）
|
||
```
|
||
|
||
### Action 3: Week 1計画レビュー（10分）
|
||
```bash
|
||
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開始前）
|
||
1. ✅ **Phase 31.3の承認**（10週間計画）
|
||
2. ✅ **Week 1開始のGO判断**（TraceBox実装 + 品質分析）
|
||
3. ✅ **リソース確保**（実装者1名 × 10週間）
|
||
|
||
### 計画中の決定（Week 3開始前）
|
||
4. ⏳ **loopform設計レビュー**（Rust実装との差分確認）
|
||
5. ⏳ **Golden Test基準策定**（パリティ95%は適切か？）
|
||
|
||
### 後回し可能（Week 6以降）
|
||
6. 🔄 **リファクタリングのスコープ調整**（P1/P2の優先順位）
|
||
7. 🔄 **ドキュメントの詳細度調整**（実装ガイドの粒度）
|
||
|
||
---
|
||
|
||
## 🚀 推奨アクション
|
||
|
||
### Phase 31.3を**承認して即座に開始**すべき理由:
|
||
|
||
1. ✅ **Phase 31完了の直後**が最適（知見が新鮮、Rust実装が参照可能）
|
||
2. ✅ **Selfhost本流化の必須ステップ**（Phase 15.76/15.77への橋渡し）
|
||
3. ✅ **投資対効果が極めて高い**（2.5人月で世界レベルの保守性達成）
|
||
4. ✅ **リスクは管理可能**（段階的実装、週次レビュー、80/20ルール）
|
||
5. ✅ **基盤は完成済み**（Hakorune VM 138%カバレッジ、@match-based dispatch完備）
|
||
|
||
### 次のステップ（今日中に実施可能）:
|
||
|
||
```bash
|
||
# 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](./SELFHOST_CLEANUP_PLAN.md)
|
||
- **即座実行**: [QUICK_START.md](./QUICK_START.md)
|
||
- **索引**: [INDEX.md](./INDEX.md)
|
||
|
||
---
|
||
|
||
**Phase 31.3: Selfhost 綺麗綺麗計画 - 今すぐ始めましょう！** 🚀
|
||
|
||
**Hakoruneが世界に誇るセルフホストシステムになる第一歩です。**
|