From b92d9f335d67922b234b9da44cc106326ec06465 Mon Sep 17 00:00:00 2001 From: nyash-codex Date: Fri, 21 Nov 2025 09:45:27 +0900 Subject: [PATCH] =?UTF-8?q?docs(mir-logs):=20MIR=E3=83=AD=E3=82=B0?= =?UTF-8?q?=E8=A6=B3=E6=B8=AC=E3=83=AA=E3=82=B9=E3=83=88=E5=AE=8C=E6=88=90?= =?UTF-8?q?=20-=20=5F=5Fmir=5F=5F.log=20=E5=85=A8=E7=AE=87=E6=89=80?= =?UTF-8?q?=E3=82=92=E5=88=86=E9=A1=9E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 25.4-C: MIR ログ観測リスト作成 ## 📋 実装内容 ### 1. ログ呼び出し全14箇所を列挙 - `rg "__mir__\\.log" lang/src -n` で全箇所を調査 - ファイル・行番号・タグ・用途を完全文書化 ### 2. 3分類に整理 #### Dev専用（11箇所）- 削除候補 - **Stage-1 CLI Debug** (10箇所): entry/config/argc debug - 制御: `STAGE1_CLI_DEBUG=1` - MIR Builder type confusion デバッグ用 - **StringHelpers Debug** (1箇所): to_i64 input debug - 制御: `NYASH_TO_I64_DEBUG=1` - Void → Integer 型崩れデバッグ用 #### 観測用（3箇所）- 残す候補 - **FuncScanner Debug** (3箇所): skip_ws loop iteration - LoopForm v2 / PHI 生成検証 - Region+next_i SSA 安定性確認 - 将来的な「MIR 観測 API」の代表例 #### コメント（1箇所） - Test file comment ### 3. 将来構想 - `MirLogBox` 箱化構想を記載 - ログレベル制御・構造化ログ・パフォーマンストレース機能 - MIR デバッガー統合の下地 ## 技術的成果 - **全箇所可視化**: 14箇所のログ用途を完全把握 - **分類明確化**: Dev専用 vs 観測用を明示 - **将来設計**: MIR 観測 API 構想を文書化 ## 文書作成 - 新規: `docs/development/architecture/mir-logs-observability.md` ## 方針 - **Phase 25.4**: ドキュメント整理のみ（コード変更なし） - **後続フェーズ**: Dev専用ログ削除・観測用ログ API化を検討 ## 参考 - Phase 25.4 全体: docs/development/roadmap/phases/phase-25.4-naming-cli-cleanup/README.md 🎉 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../architecture/mir-logs-observability.md | 156 ++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 docs/development/architecture/mir-logs-observability.md diff --git a/docs/development/architecture/mir-logs-observability.md b/docs/development/architecture/mir-logs-observability.md new file mode 100644 index 00000000..1e63b044 --- /dev/null +++ b/docs/development/architecture/mir-logs-observability.md @@ -0,0 +1,156 @@ +# MIR ログ観測 (`__mir__.log`) + +**目的**: `__mir__.log` の全使用箇所を一覧化し、dev専用か観測用かを分類する。 + +--- + +## 概要 + +`__mir__.log` は MIR レベルの観測・デバッグ用ログ出力。将来的にはdev向けの一時的なログと、本番でも使うMIR観測 APIに分離する予定。 + +--- + +## 使用箇所一覧表 + +### 1. Stage-1 CLI Debug（10箇所） + +**場所**: `lang/src/runner/stage1_cli.hako` + +| 行番号 | タグ | 説明 | 用途 | +|-------|------|-----|------| +| 157 | `[stage1_main] args_safe at entry` | stage1_main entry point args debug | Dev専用 | +| 171 | `[stage1_main] config` | Config box values debug | Dev専用 | +| 231 | `[_cmd_emit] args before size check` | _cmd_emit args debug | Dev専用 | +| 235 | `[_cmd_emit] argc after size` | _cmd_emit argc debug | Dev専用 | +| 254 | `[_cmd_emit_program_json] args before size check` | _cmd_emit_program_json args debug | Dev専用 | +| 258 | `[_cmd_emit_program_json] argc after size` | _cmd_emit_program_json argc debug | Dev専用 | +| 282 | `[_cmd_emit_mir_json] args before size check` | _cmd_emit_mir_json args debug | Dev専用 | +| 286 | `[_cmd_emit_mir_json] argc after size` | _cmd_emit_mir_json argc debug | Dev専用 | +| 348 | `[_cmd_run] args before size check` | _cmd_run args debug | Dev専用 | +| 352 | `[_cmd_run] argc after size` | _cmd_run argc debug | Dev専用 | + +**有効化環境変数**: `STAGE1_CLI_DEBUG=1` + +**説明**: +- Stage-1 CLI の entry point / config 値のデバッグ +- MIR Builder type confusion およびValueId 伝搬の検証用 +- argv/argc の SSA 変数追跡 + +**用途と削除時期**: +- Phase 25.x 完了後に MIR Builder type confusion 修正完了で削除予定 +- Config box の初期化検証が完了したら不要になる debug ログが含まれる可能性あり + +--- + +### 2. FuncScanner Debug（3箇所） + +**場所**: `lang/src/compiler/entry/func_scanner.hako` + +| 行番号 | タグ | 説明 | 用途 | +|-------|------|-----|------| +| 315 | `skip_ws/head` | skip_ws loop head (i, n) | 観測用 | +| 319 | `skip_ws/loop` | skip_ws loop iteration (i, n) | 観測用 | +| 326 | `skip_ws/exit` | skip_ws loop exit (i, n) | 観測用 | + +**有効化環境変数**: 現在明示的な環境変数なし + +**説明**: +- FuncScanner の skip_ws ループの反復をMIR レベルで観測 +- LoopForm v2 / PHI 機能の正しさを検証 +- Region+next_i 伝播の SSA 動作確認 + +**用途と削除時期**: +- **保持推奨**: 将来的な MIR 観測は、用途に応じてMIR観測 APIとして昇格が望ましい +- 当面は明示的な環境変数（例: `NYASH_FUNCSCANNER_DEBUG=1`）で制御することも検討 + +--- + +### 3. StringHelpers Debug（1箇所） + +**場所**: `lang/src/shared/common/string_helpers.hako` + +| 行番号 | タグ | 説明 | 用途 | +|-------|------|-----|------| +| 27 | `[string_helpers/to_i64] x` | to_i64 input value debug | Dev専用 | + +**有効化環境変数**: `NYASH_TO_I64_DEBUG=1` + +**説明**: +- Void 型が Integer として扱われる問題の検証用 +- `NYASH_TO_I64_FORCE_ZERO` workaround の正しさを確認 + +**用途と削除時期**: +- Phase 25.x 完了後に型伝播が正しく修正されたら削除予定 +- 型強制処理の妥当性が確立したら不要になる + +--- + +### 4. Test Comment（1箇所） + +**場所**: `lang/src/compiler/tests/funcscanner_skip_ws_min.hako` + +| 行番号 | タグ | 説明 | 用途 | +|-------|------|-----|------| +| 6 | (コメント内) | テスト場所の注釈 | コメント | + +**説明**: `__mir__.log` の使用例をコメントで示す + +--- + +## 用途別集計表 + +| 用途 | 件数 | 内容 | 用途と削除時期 | +|-----|-------|-----|----------| +| **Dev専用** | 11 | Stage-1 CLI / StringHelpers デバッグ用 | 削除予定（Phase 25.x 完了） | +| **観測用** | 3 | FuncScanner ループ反復観測 | 保持推奨（MIR観測 API 昇格） | +| **コメント** | 1 | テスト場所の注釈 | - | + +--- + +## 用途に応じたMIR観測 API 設計（Phase 25.x 完了後） + +将来的な `__mir__.log` は暫定的な環境変数制御から脱却し、用途に応じて `MirLogBox` 等の箱化されたAPI経由で呼び出す形に整理することが望ましい。 + +### 設計例 +```nyash +static box MirLogBox { + // Structured logging with levels + method debug(tag, ...values) { + if env.get("NYASH_MIR_LOG_LEVEL") != "debug" { return } + // ... implementation + } + + method trace(tag, ...values) { + if env.get("NYASH_MIR_LOG_LEVEL") != "trace" { return } + // ... implementation + } + + // Performance tracing + method trace_loop_iteration(loop_id, iteration, vars) { + // ... implementation + } +} +``` + +### 利点 +- ログレベル設定（debug/trace/info） +- 条件付き出力（JSON形式等） +- 統合デバッグ機能拡張 +- 用途に応じたMIR 観測とデバッグの分離 + +--- + +## コードの削除方針（Phase 25.4） + +**現在の戦略では `__mir__` 使用箇所そのものには変更を加えず、分類と削除方針のみを記録。** + +削除や統合は将来的な環境変数整理や機能分類時に実施する。 + +--- + +## 参考 + +- Phase 25.4 計画: `docs/development/roadmap/phases/phase-25.4-naming-cli-cleanup/README.md` +- Stage-1 CLI: `lang/src/runner/stage1_cli.hako` +- FuncScanner: `lang/src/compiler/entry/func_scanner.hako` +- StringHelpers: `lang/src/shared/common/string_helpers.hako`