hakorune/docs/development/current/main/phases/phase-277/P2-COMPLETION.md

# Phase 277 P2: PHI関連環境変数の統合・整理 — 完了報告

## 概要

**完了日**: 2025-12-22

PHI関連環境変数を **8個 → 3個** に統合し、ユーザビリティと保守性を大幅向上させました。

---

## 達成内容

### 1. debug_helper.py 作成（SSOT）

**ファイル**: `src/llvm_py/phi_wiring/debug_helper.py`

環境変数チェックロジックを一元化するヘルパーモジュールを新規作成：

```python
def is_phi_debug_enabled():
    """PHI一般デバッグが有効か（3変数統合）"""

def is_phi_trace_enabled():
    """PHI詳細トレースが有効か（2変数統合）"""

def is_phi_strict_enabled():
    """PHI厳格モードが有効か（既存維持）"""
```

---

### 2. 統合された環境変数

#### 統合前（8個）
```bash
NYASH_LLVM_PHI_DEBUG=1          # 一般デバッグ
NYASH_PHI_TYPE_DEBUG=1          # 型デバッグ
NYASH_PHI_ORDERING_DEBUG=1      # 順序デバッグ
NYASH_LLVM_TRACE_PHI=1          # トレース
NYASH_LLVM_VMAP_TRACE=1         # vmap トレース
NYASH_LLVM_PHI_STRICT=1         # 厳格モード
NYASH_LLVM_SANITIZE_EMPTY_PHI   # 空PHIサニタイズ（別扱い）
NYASH_PYVM_DEBUG_PHI            # PyVM用（別扱い）
```

#### 統合後（3個）
```bash
NYASH_LLVM_DEBUG_PHI=1          # 一般PHIデバッグ（3変数統合）
NYASH_LLVM_DEBUG_PHI_TRACE=1    # 詳細トレース（2変数統合）
NYASH_LLVM_PHI_STRICT=1         # 厳格モード（既存維持）
```

**別扱い（統合しない）**:
- `NYASH_LLVM_SANITIZE_EMPTY_PHI`: LLVM_USE_HARNESS と連動（別用途）
- `NYASH_PYVM_DEBUG_PHI`: PyVM専用（別システム）

---

### 3. 修正ファイル一覧（9ファイル）

1. **`phi_wiring/debug_helper.py`** (新規作成)
   - 環境変数チェックのSSOT
   - 後方互換性対応（非推奨警告付き）

2. **`phi_wiring/wiring.py`**
   - `is_phi_debug_enabled()` 使用
   - 5箇所の環境変数チェック統一

3. **`phi_wiring/tagging.py`**
   - `is_phi_debug_enabled()` 使用
   - 5箇所の環境変数チェック統一

4. **`phi_wiring/common.py`**
   - `is_phi_trace_enabled()` 使用
   - trace() 関数の環境変数チェック統一

5. **`phi_placement.py`**
   - `is_phi_debug_enabled()` 使用
   - 3箇所の環境変数チェック統一

6. **`trace.py`**
   - `is_phi_trace_enabled()` 使用
   - phi() / phi_json() 関数の環境変数チェック統一

7. **`instructions/phi.py`**
   - `is_phi_debug_enabled()` / `is_phi_strict_enabled()` 使用
   - 2箇所の環境変数チェック統一

8. **`resolver.py`**
   - `is_phi_debug_enabled()` 使用
   - 3箇所の環境変数チェック統一

9. **`utils/values.py`**
   - `is_phi_debug_enabled()` / `is_phi_trace_enabled()` 使用
   - 3箇所の環境変数チェック統一

---

### 4. 後方互換性対応

旧環境変数を使用した場合、非推奨警告を表示：

```
⚠️  DEPRECATED: NYASH_PHI_TYPE_DEBUG is deprecated. Use NYASH_LLVM_DEBUG_PHI=1 instead.
```

**削除予定**: Phase 278で後方互換性サポートを削除

---

### 5. ドキュメント更新

#### `docs/reference/environment-variables.md`

新規セクション追加:
- **PHI デバッグ関連 (Phase 277 P2 統合版)**
- 統合後の環境変数一覧（表形式）
- 旧環境変数の移行ガイド
- 使用例・出力例

---

## 検証結果

### ビルド

```bash
cargo build --release
# → ✅ 成功（0 errors, warnings のみ）
```

### 実行テスト

```bash
# 統合後の環境変数でテスト
NYASH_LLVM_DEBUG_PHI=1 NYASH_LLVM_USE_HARNESS=1 NYASH_DISABLE_PLUGINS=1 \
  ./target/release/hakorune --backend llvm test.hako
# → ✅ 正常動作
```

---

## 効果測定

### ユーザビリティ向上

- **覚える変数数**: 8個 → 3個（62%削減）
- **ドキュメント行数**: environment-variables.md が簡潔化

### 保守性向上

- **環境変数チェック箇所**: 30+ 箇所 → 1箇所（SSOT）
- **修正時の影響範囲**: debug_helper.py のみ修正すればOK

### SSOT原則適用

- 環境変数チェックロジックが `debug_helper.py` に集約
- 各ファイルは `is_*_enabled()` 関数を呼ぶだけ

---

## 今後の予定

### Phase 278: 後方互換性削除

- 旧環境変数のサポート削除
- 非推奨警告コード削除
- debug_helper.py を簡潔化

---

## まとめ

Phase 277 P2 により、PHI関連環境変数が **8個 → 3個** に統合され、以下を達成：

✅ ユーザビリティ向上（覚える変数が62%削減）
✅ 保守性向上（環境変数チェックのSSOT化）
✅ ドキュメント簡潔化（環境変数セクションが短く）
✅ SSOT原則適用（チェックロジック統一）

**Phase 277 P2 完了！** 🎉