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

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

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

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

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

---

2. 統合された環境変数

統合前（8個）

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個）

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 統合版)
• 統合後の環境変数一覧（表形式）
• 旧環境変数の移行ガイド
• 使用例・出力例

---

検証結果

ビルド

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

実行テスト

# 統合後の環境変数でテスト
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 完了！ 🎉