From d75bbf4f90833c7ddc5f2ccfb271b5d5e12b28f6 Mon Sep 17 00:00:00 2001
From: nyash-codex <codex@nyash.local>
Date: Thu, 4 Dec 2025 14:10:51 +0900
Subject: [PATCH] =?UTF-8?q?docs(phase153):=20hako=5Fcheck=20/=20dead=20cod?=
 =?UTF-8?q?e=20=E6=A4=9C=E5=87=BA=E3=83=A2=E3=83=BC=E3=83=89=E3=81=AE?=
 =?UTF-8?q?=E5=BE=A9=E6=B4=BB=EF=BC=88=E6=8C=87=E7=A4=BA=E6=9B=B8=E4=BD=9C?=
 =?UTF-8?q?=E6=88=90=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 153 指示書:
- hako_check を JoinIR 専用パイプラインで安定稼働
- dead code 検出モード復活（DeadCodeAnalyzerBox 箱化）
- CLI フラグ `--dead-code` でモード切り替え
- ENV 追加なし（将来必要になったら追加）

6 Tasks:
1. hako_check 現状インベントリ
2. JoinIR 専用パイプライン確認
3. DeadCodeAnalyzerBox 設計（箱化）
4. 実装と CLI 統合
5. テストとスモーク
6. ドキュメント更新

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../main/phase153_hako_check_deadcode.md      | 244 ++++++++++++++++++
 1 file changed, 244 insertions(+)
 create mode 100644 docs/development/current/main/phase153_hako_check_deadcode.md

diff --git a/docs/development/current/main/phase153_hako_check_deadcode.md b/docs/development/current/main/phase153_hako_check_deadcode.md
new file mode 100644
index 00000000..7c3d2eef
--- /dev/null
+++ b/docs/development/current/main/phase153_hako_check_deadcode.md
@@ -0,0 +1,244 @@
+# Phase 153: hako_check / dead code 検出モードの復活（JoinIR 版）
+
+## 0. ゴール
+
+**hako_check を JoinIR 専用パイプラインの上で安定稼働させ、以前できていた「未使用関数・デッドコード検出」モードを、今の構造に合わせて復活・整備する。**
+
+目的：
+- selfhost / .hako 側のコンパイラコードに対して、hako_check で死んだ関数・到達しない分岐をすぐ見つけられる状態を作る
+- Phase 160+ の .hako JoinIR/MIR 移植に入ったときの安全ネットを確立する
+
+---
+
+## 1. Scope / Non-scope
+
+### ✅ やること
+
+1. **hako_check の現状インベントリ**
+   - CLI スクリプト (`tools/hako_check.sh` / `tools/hako_check/*.hako`) と実行経路を確認
+   - 「何をチェックしているか」「以前動いていた dead code モードが今どうなっているか」を整理
+
+2. **JoinIR 専用 hako_check パイプラインの再確認**
+   - Phase 121–124 の設計どおり、AST→JoinIR→MIR→解析が一つの線になっているかを確認・doc 固定
+
+3. **dead code 検出モードの再実装／復活（箱化モジュール化）**
+   - 「未呼び出しの関数」「reachable ではない cfg ノード」などの検出を、今の JoinIR/MIR 情報から計算
+   - 結果を CLI から見やすい形（テキスト）で出力
+   - **DeadCodeAnalyzerBox** として箱化
+
+4. **テストとスモーク**
+   - 小さい .hako フィクスチャで「明らかに死んでいる関数」が検出できることを確認
+   - 既存の hako_check テストが退行していないことを確認
+
+### ❌ やらないこと
+
+- JoinIR / MIR の意味論を変えない（解析は「読むだけ」）
+- 新しい Stage‑3 構文を追加しない（Phase 152-A/B で決めた範囲のまま）
+- 環境変数を増やさない（CLI フラグ `--dead-code` のみ。必要になったら後で追加）
+
+---
+
+## 2. Task 1: hako_check 現状インベントリ
+
+### 対象ファイル
+
+- `tools/hako_check.sh`
+- `tools/hako_check/*.hako`（CLI エントリ・本体）
+- `docs/development/` 内の hako_check 関連 doc：
+  - `hako_check_design.md`
+  - `phase121_*`
+  - `phase124_hako_check_joinir_finalization.md`
+
+### やること
+
+1. **hako_check の実行フローを再確認**
+   - CLI → .hako スクリプト → VM → MirBuilder / JoinIR → 解析、という線を図にする
+
+2. **以前の dead code モードの存在を調査**
+   - 関数名に `dead` / `unused` / `reachability` 等が含まれる Box や関数を探す
+   - 設計 doc に「dead code モード」がどう書かれていたかを確認
+
+3. **結果をドキュメントにまとめる**
+   - `docs/development/current/main/phase153_hako_check_inventory.md`（新規）に：
+     - エントリポイント
+     - 現在有効なチェック種類
+     - 死んでいる / 途中まで実装されていた dead code 検出の一覧
+   を書き出す
+
+### 成果物
+
+- `phase153_hako_check_inventory.md` 作成
+
+---
+
+## 3. Task 2: JoinIR 専用パイプラインの再確認と固定
+
+### 目的
+
+Phase 123–124 で「hako_check を JoinIR 専用にした」設計が、実際のコードでも守られているか確認
+
+### やること
+
+1. MirBuilder / JoinIR lowering で、hako_check 用の関数がどのルートを通っているかを確認
+
+2. もしまだ legacy PHI / 旧 LoopBuilder にフォールバックしている箇所があれば：
+   - hako_check 経路だけでも確実に JoinIR 経由になるように修正する案を設計（実装は別フェーズでも可）
+
+3. `hako_check_design.md` / `phase121_integration_roadmap.md` に：
+   - AST→JoinIR→MIR→hako_check の経路を最終形として追記
+
+### 成果物
+
+- パイプライン確認結果の記録（インベントリ doc に追記でも可）
+
+---
+
+## 4. Task 3: dead code 検出モードの設計（箱化モジュール化）
+
+### 目的
+
+hako_check 内で dead code 判定を行う「箱」を 1 個に閉じ込める
+
+### 方針
+
+- JoinIR/MIR の CFG/シンボル情報を読んで：
+  - 入口（エントリポイント関数）からの到達可能性を DFS/BFS
+  - 到達しなかった関数・ブロック・分岐を列挙
+
+### 箱単位の設計
+
+**DeadCodeAnalyzerBox** として：
+- 入力: Program JSON v0 / MIR JSON / JoinIR JSON
+- 出力: 「未使用関数名」「未到達ブロックID」のリスト
+
+### やること
+
+1. どのフォーマットを入力にするか決める
+   - 解析専用なら MIR JSON v0 / JoinIR JSON のどちらか
+   - 既存の hako_check 本体がどちらを見やすいかも考える
+
+2. Dead code 箱の API を決める（.hako レベルの関数シグネチャ）
+
+3. 出力フォーマット（CLI 表示）のラフ案：
+   ```
+   unused function: Foo.bar/1
+   unreachable block: fn=Main.main bb=10 (if false branch)
+   ```
+
+### 成果物
+
+- DeadCodeAnalyzerBox の設計（API シグネチャ）
+- 入力フォーマット決定
+
+---
+
+## 5. Task 4: dead code 検出モードの実装と CLI 統合
+
+### 実装
+
+- hako_check 本体 .hako に **DeadCodeAnalyzerBox** を追加
+- 入口の CLI から、`--dead-code` フラグで dead code モードを選べるようにする
+
+### CLI 挙動
+
+```bash
+# 従来の基本チェック
+hako_check target.hako
+
+# dead code レポートを追加表示
+hako_check --dead-code target.hako
+```
+
+### 環境変数について
+
+- **Phase 153 では ENV 追加なし**（CLI フラグのみ）
+- 将来「CI からフラグを渡しにくい」等のニーズが出たら、そのときに `NYASH_HAKO_CHECK_DEAD=1` を 1 個だけ足す
+
+### 成果物
+
+- DeadCodeAnalyzerBox の実装
+- hako_check CLI に `--dead-code` フラグ追加
+
+---
+
+## 6. Task 5: テストとスモーク
+
+### テスト用 .hako を 2〜3 本作る
+
+1. **単純に未使用関数 1 個だけあるケース**
+2. **入口から到達しない if/loop 分岐を含むケース**
+3. **selfhost 関連の .hako から代表 1 本**（小さなコンパイラ部品）を選び、未使用関数が検出できるか見る
+
+### スモークスクリプト
+
+- `tools/hako_check_deadcode_smoke.sh`（など）を作成し：
+  - 上のテスト .hako をまとめて実行
+  - 期待する dead code 行が出ているかを軽く grep
+
+### JoinIR 依存の確認
+
+- 少なくとも代表 1 本は JoinIR lowering → MIR → hako_check まで通し、
+  Rust VM と hako_check の結果が論理的に矛盾していないことを確認
+
+### 成果物
+
+- テスト .hako 2〜3 本
+- `tools/hako_check_deadcode_smoke.sh`
+
+---
+
+## 7. Task 6: ドキュメント / CURRENT_TASK 更新
+
+### ドキュメント更新
+
+1. **phase153_hako_check_inventory.md** に：
+   - どのモードがあり、今どこまで動くかを確定版として追記
+
+2. **hako_check_design.md** を更新：
+   - 新しい dead code モードの説明と CLI/API を追加
+
+3. **CURRENT_TASK.md**：
+   - Phase 153 セクションを追加し、以下を 2〜3 行で書く：
+     - 「hako_check が JoinIR 専用パイプラインで動き、dead code モードが復活した」
+     - 「これを .hako JoinIR/MIR 移植時の安全ネットとして使う」
+
+### 成果物
+
+- 各種ドキュメント更新
+- git commit
+
+---
+
+## ✅ 完成チェックリスト（Phase 153）
+
+- [ ] Task 1: hako_check 現状インベントリ完了
+  - [ ] phase153_hako_check_inventory.md 作成
+- [ ] Task 2: JoinIR 専用パイプライン確認
+  - [ ] パイプライン図確定・記録
+- [ ] Task 3: DeadCodeAnalyzerBox 設計
+  - [ ] API シグネチャ決定
+  - [ ] 入力フォーマット決定
+- [ ] Task 4: 実装と CLI 統合
+  - [ ] DeadCodeAnalyzerBox 実装
+  - [ ] `--dead-code` フラグ追加
+- [ ] Task 5: テストとスモーク
+  - [ ] テスト .hako 作成（2〜3 本）
+  - [ ] hako_check_deadcode_smoke.sh 作成
+- [ ] Task 6: ドキュメント更新
+  - [ ] phase153_hako_check_inventory.md 確定版
+  - [ ] hako_check_design.md 更新
+  - [ ] CURRENT_TASK.md 更新
+  - [ ] git commit
+
+---
+
+## 次のステップ
+
+Phase 153 完了後：
+- **Phase 160+**: .hako JoinIR/MIR 移植章（hako_check が安全ネットとして機能）
+- **Phase 200+**: Python → Hakorune トランスパイラ構想
+
+---
+
+**作成日**: 2025-12-04
+**Phase**: 153（hako_check / dead code 検出モードの復活）