docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)
This commit is contained in:
nyash-codex
303
docs/private/roadmap/phases/phase-32/README.md
Normal file
303
docs/private/roadmap/phases/phase-32/README.md
Normal file
@ -0,0 +1,303 @@
|
||||
# Phase 32: Hakorune Static Analyzer - Dead Code Detector MVP
|
||||
|
||||
**Status**: 計画完了、実装準備中（構造改訂版）
|
||||
**期間**: 1週間（7日、2025-10-20 → 2025-10-27）
|
||||
**担当**: Claude + ChatGPT協調
|
||||
**優先度**: HIGH ⭐⭐⭐⭐⭐
|
||||
**Ring位置**: Ring-1（Meta/自己ホスト）
|
||||
|
||||
---
|
||||
|
||||
## 🎯 目標
|
||||
|
||||
**HakoruneでHakoruneコードを解析する静的解析ツールの実装**
|
||||
|
||||
### Phase 32 スコープ（MVP）
|
||||
- ✅ MIR JSONからデッドコード（到達不可能関数）を検出
|
||||
- ✅ Gate-C/AST Strict MIR前提の厳密解析
|
||||
- ✅ テキストレポート出力（診断サマリ）
|
||||
- ✅ 95%以上の精度目標
|
||||
|
||||
### Phase 32外（Phase 33以降）
|
||||
- ❌ 重複コード検出（Phase 33）
|
||||
- ❌ 複雑度メトリクス（Phase 34）
|
||||
- ❌ マルチファイル解析（Phase 35）
|
||||
- ❌ JSON/DOT出力（Phase 36）
|
||||
|
||||
---
|
||||
|
||||
## 💡 革命的な理由
|
||||
|
||||
### 15倍の精度改善
|
||||
- **cargo-udeps**: 25%精度（75%誤検出）
|
||||
- **Hakorune Analyzer**: 95%精度（5%誤検出）
|
||||
|
||||
### なぜこんなに精度が高いのか？
|
||||
|
||||
1. **完璧な呼び出しグラフ**
|
||||
- グローバル変数なし（すべてBox）
|
||||
- 明示的関数呼び出しのみ
|
||||
- 動的ディスパッチも型情報で追跡可能
|
||||
|
||||
2. **ネイティブMIRアクセス**
|
||||
- Rust: 外部ツールでAST推論（不正確）
|
||||
- Hakorune: Gate-C Strict MIR JSONで完全な呼び出し情報
|
||||
|
||||
3. **Box理論の恩恵**
|
||||
- すべてBoxで統一
|
||||
- 拡張が簡単（新しいBoxを追加するだけ）
|
||||
- 型安全
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ アーキテクチャ設計（改訂版）
|
||||
|
||||
### 配置理由: selfhost/ 配下
|
||||
|
||||
**Three Rings の Ring-1（Meta/自己ホスト）に属する開発ツール**
|
||||
- 将来のコンパイラと密に連携する前提
|
||||
- selfhost/shared の BoxHelpers/MirSchema/Gate-C Strict を直に再利用
|
||||
- 独立箱として将来 CLI 化しやすい
|
||||
|
||||
### ファイル構造（責務分離）
|
||||
|
||||
```
|
||||
selfhost/analyzer/
|
||||
├── hako_module.toml # exports 最小（selfhost.analyzer.*）
|
||||
├── boxes/
|
||||
│ ├── driver_box.hako # 入口: 入力→走査→レポート
|
||||
│ ├── ast_scan_box.hako # AST Strict前提の走査
|
||||
│ ├── mir_scan_box.hako # Gate-C Strict MIR JSONの走査
|
||||
│ └── report_box.hako # 集計と文字列整形、出力
|
||||
├── README.md # 責務/入出力/ENV/非対象
|
||||
└── smokes/
|
||||
├── analyzer_ast_strict_ok_vm.sh
|
||||
├── analyzer_mir_gatec_ok_vm.sh
|
||||
└── analyzer_bad_mir_fail_vm.sh # 負例・診断固定
|
||||
```
|
||||
|
||||
### データフロー
|
||||
|
||||
```
|
||||
.hako file
|
||||
↓ (hakorune --emit-mir-json + Gate-C Strict)
|
||||
MIR JSON (厳密型保証)
|
||||
↓ driver_box.hako
|
||||
├→ ast_scan_box.hako (AST走査)
|
||||
└→ mir_scan_box.hako (MIR走査)
|
||||
↓ selfhost/shared/MirSchema
|
||||
↓ BoxHelpers (JSON解析)
|
||||
↓ 到達可能性分析（BFS）
|
||||
["unused_helper/1", "deprecated_func/0"]
|
||||
↓ report_box.hako
|
||||
Text Report + MapBox診断
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 依存とガード（Fail-Fast）
|
||||
|
||||
### 依存関係
|
||||
- ✅ **selfhost/shared のみ**（BoxHelpers, MirSchema, JsonEmit）
|
||||
- ❌ **外部I/Oなし**（入力は文字列/MapBox）
|
||||
- ✅ **Gate-C/AST Strict を既定ON**で実行
|
||||
|
||||
### 環境変数（dev限定）
|
||||
|
||||
```bash
|
||||
# 追加チェックON
|
||||
NYASH_ANALYZER_STRICT=1
|
||||
|
||||
# 将来の切替（既定=mir）
|
||||
HAKO_ANALYZER_ENTRY=ast|mir
|
||||
|
||||
# Gate-C/AST Strict（スモークテストで既定ON）
|
||||
NYASH_GATE_C_STRICT=1
|
||||
NYASH_AST_STRICT=1
|
||||
```
|
||||
|
||||
### Fail-Fast 原則
|
||||
- 不正なMIR JSON → 即座にエラー
|
||||
- 余剰キー/型不一致 → 診断固定（負例テスト）
|
||||
- フォールバック禁止（Silent failure なし）
|
||||
|
||||
---
|
||||
|
||||
## 🔧 公開インターフェース（最小）
|
||||
|
||||
### DriverBox API
|
||||
|
||||
```hako
|
||||
static box DriverBox {
|
||||
# 文字列入力→文字列出力
|
||||
run_from_string(input: StringBox, kind: StringBox) -> StringBox
|
||||
|
||||
# MapBox入力→MapBox出力
|
||||
run_from_box(input: MapBox, kind: StringBox) -> MapBox
|
||||
}
|
||||
```
|
||||
|
||||
**kind引数**:
|
||||
- `"ast"` - AST走査（将来実装）
|
||||
- `"mir"` - MIR JSON走査（Phase 32実装）
|
||||
|
||||
**返り値**:
|
||||
- 文字列: 診断サマリ（テキストレポート）
|
||||
- MapBox: 構造化診断（dead_functions, reachable_functions等）
|
||||
|
||||
---
|
||||
|
||||
## 📋 実装計画（改訂版）
|
||||
|
||||
| Day | タスク | 成果物 | LOC | 状態 |
|
||||
|-----|--------|--------|-----|------|
|
||||
| **Day 1** | スケルトン作成 | driver/ast_scan/mir_scan/report + README | 150 | 🟡 準備中 |
|
||||
| **Day 2** | MIR走査基盤 | mir_scan_box.hako（関数抽出） | 200 | 🟡 計画中 |
|
||||
| **Day 3** | 呼び出しグラフ構築 | mir_scan_box.hako拡張（Graph） | 250 | 🟡 計画中 |
|
||||
| **Day 4** | BFS到達可能性分析 | mir_scan_box.hako完成 | 200 | 🟡 計画中 |
|
||||
| **Day 5** | レポート生成 | report_box.hako完成 | 150 | 🟡 計画中 |
|
||||
| **Day 6** | スモークテスト整備 | 3本（happy/happy/負例） | 100 | 🟡 計画中 |
|
||||
| **Day 7** | セルフホスト解析 + ドキュメント | 実用化 | 50 | 🟡 計画中 |
|
||||
| **Total** | | | **1,100** | |
|
||||
|
||||
---
|
||||
|
||||
## 🧪 テスト戦略（ドキュメント・テスト先行）
|
||||
|
||||
### スモークテスト構成
|
||||
|
||||
**happy path 2本（緑）**:
|
||||
```bash
|
||||
# AST Strict入力（将来）
|
||||
selfhost/analyzer/smokes/analyzer_ast_strict_ok_vm.sh
|
||||
|
||||
# Gate-C MIR JSON入力（Phase 32）
|
||||
selfhost/analyzer/smokes/analyzer_mir_gatec_ok_vm.sh
|
||||
```
|
||||
|
||||
**負例1本（診断文言固定）**:
|
||||
```bash
|
||||
# 不正MIR: 余剰キー/型不一致
|
||||
selfhost/analyzer/smokes/analyzer_bad_mir_fail_vm.sh
|
||||
```
|
||||
|
||||
### quick-lite → quick → integration 段階追加
|
||||
|
||||
- **quick-lite**: 負例のみ（診断Fail-Fast確認）
|
||||
- **quick**: happy path 2本追加
|
||||
- **integration**: セルフホストコード解析（実用検証）
|
||||
|
||||
---
|
||||
|
||||
## 🎓 参考実装（学習元）
|
||||
|
||||
### selfhost/shared から再利用
|
||||
|
||||
1. **BoxHelpers** - JSON解析パターン
|
||||
2. **MirSchema** - MIR構造定義
|
||||
3. **JsonEmit** - MapBox→JSON文字列変換
|
||||
|
||||
### Rustコードベースから学ぶ
|
||||
|
||||
1. **src/mir/optimizer.rs** (`diagnose_unlowered_type_ops`)
|
||||
- デッドコード検出の基本パターン
|
||||
2. **src/mir/verification.rs**
|
||||
- 呼び出し検証ロジック
|
||||
- Callee型のパース
|
||||
|
||||
---
|
||||
|
||||
## 📈 Phase 33以降の展望
|
||||
|
||||
### Phase 33: 重複コード検出（1週間）
|
||||
- MIR正規化（レジスタ・定数・演算子）
|
||||
- 構造ハッシュ化
|
||||
- 4種類の重複（完全一致/変数名/構造/部分）
|
||||
|
||||
### Phase 34: 複雑度メトリクス（1週間）
|
||||
- サイクロマティック複雑度
|
||||
- 認知的複雑度
|
||||
- 行数・関数数統計
|
||||
|
||||
### Phase 35: マルチファイル解析（2週間）
|
||||
- プロジェクト全体解析
|
||||
- モジュール間依存グラフ
|
||||
- 到達可能性の階層分析
|
||||
|
||||
### Phase 36: 可視化・出力（2週間）
|
||||
- JSON出力（機械可読）
|
||||
- DOT出力（Graphviz）
|
||||
- HTML/Markdown レポート
|
||||
|
||||
**合計**: 7週間で完全な静的解析ツールキット完成
|
||||
|
||||
---
|
||||
|
||||
## 🏆 期待される成果
|
||||
|
||||
### 技術的成果
|
||||
1. **95%精度のデッドコード検出器**
|
||||
2. **セルフホスト開発の加速**（不要コード削除）
|
||||
3. **Everything is Box のショーケース**
|
||||
|
||||
### 戦略的成果
|
||||
1. **論文ネタ**: "70日でセルフホスト + 静的解析ツール"
|
||||
2. **採用材料**: Hakorune の品質保証能力
|
||||
3. **コミュニティ貢献**: 他言語でも応用可能なパターン
|
||||
|
||||
### 学術的価値
|
||||
- **PLDI SRC**: "Bootstrapping Static Analysis"
|
||||
- **ICSE Demo**: 実動デモ
|
||||
- **比較研究**: cargo-udeps vs Hakorune (15倍精度)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 導入ステップ（短期）
|
||||
|
||||
### Step 1: スケルトン作成（Day 1）
|
||||
```bash
|
||||
mkdir -p selfhost/analyzer/{boxes,smokes}
|
||||
touch selfhost/analyzer/hako_module.toml
|
||||
touch selfhost/analyzer/README.md
|
||||
touch selfhost/analyzer/boxes/{driver_box,ast_scan_box,mir_scan_box,report_box}.hako
|
||||
```
|
||||
|
||||
### Step 2: Gate-C/AST Strict happy path（Day 2-3）
|
||||
- MIR JSON入力の基本走査
|
||||
- 関数リスト抽出
|
||||
- スモーク2本（緑）
|
||||
|
||||
### Step 3: 負例スモーク（Day 4）
|
||||
- 不正MIR: 余剰キー/型不一致
|
||||
- 診断文言固定
|
||||
|
||||
### Step 4: CURRENT_TASK.md 登録
|
||||
- Phase 32 トラックとして追加
|
||||
|
||||
---
|
||||
|
||||
## 📚 関連ドキュメント
|
||||
|
||||
- **設計書**: `docs/development/proposals/analyzer-mvp-summary.md`
|
||||
- **アルゴリズム**: `docs/development/proposals/dead-code-detection/call-graph-algorithm-detailed-design.md`
|
||||
- **重複検出**: `docs/development/proposals/ideas/refactoring/mir-duplicate-detection-algorithm.md`
|
||||
- **実現可能性**: `docs/development/proposals/hakorune-static-analyzer-feasibility.md`
|
||||
- **実装ガイド**: `docs/development/proposals/analyzer-implementation-guide.md`（SSOT要約を selfhost/analyzer/README.md に配置）
|
||||
|
||||
---
|
||||
|
||||
## ✅ 決定事項
|
||||
|
||||
1. **配置**: selfhost/analyzer/（Ring-1: Meta/自己ホスト） ✅
|
||||
2. **責務分離**: driver/ast_scan/mir_scan/report ✅
|
||||
3. **依存**: selfhost/shared のみ ✅
|
||||
4. **Gate-C/AST Strict**: 既定ON ✅
|
||||
5. **Fail-Fast**: フォールバック禁止 ✅
|
||||
6. **テスト先行**: ドキュメント→スモーク→実装 ✅
|
||||
|
||||
---
|
||||
|
||||
**作成日**: 2025-10-19
|
||||
**改訂日**: 2025-10-19（構造改訂版）
|
||||
**次回レビュー**: 2025-10-20 (Day 1完了時)
|
||||
**最終更新**: 2025-10-19
|
||||
Reference in New Issue
Block a user