hakorune/docs/private/roadmap/phases/phase-32/README.md

# 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