# 機能設計書 74-デバッグ情報

## 概要

本ドキュメントは、Nushellのデバッグ情報機能の設計仕様を定義する。debug コマンド群は、値のデバッグ出力、プロセス情報、環境情報、プロファイリングなど、開発・トラブルシューティングのための機能を提供する。

### 本機能の処理概要

debugコマンド群は、Nushellのスクリプトやコマンドの開発・デバッグを支援するための機能を提供する。値の詳細表示、プロセスメモリ情報、環境変数情報、クロージャのプロファイリングなど、多岐にわたるデバッグ機能を含む。

**業務上の目的・背景**：シェルスクリプトやコマンドの開発において、データの構造確認やパフォーマンス測定は不可欠である。本機能により、値の内部表現の確認、メモリ使用量の監視、実行時間の計測が可能になり、効率的な開発とトラブルシューティングを実現する。

**機能の利用シーン**：
- 複雑なデータ構造の内部表現を確認したい場合
- メモリ使用量やプロセス状態を監視したい場合
- クロージャの実行パフォーマンスを測定したい場合
- 環境変数の設定状況を確認したい場合

**主要な処理内容**：
1. `debug`：値のデバッグ出力（raw/raw-value表示対応）
2. `debug info`：プロセスメモリ情報、システム情報の表示
3. `debug profile`：クロージャのプロファイリング（IR命令レベル）
4. `debug env`：環境変数情報の表示

**関連システム・外部連携**：
- sysinfoクレート：システムメモリ・プロセス情報の取得
- nu-protocol::debugger：プロファイリング機能

**権限による制御**：特になし。プロセス情報取得はOS権限に依存。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 主画面 | debugコマンドの実行と結果表示 |
| 10 | LSP言語サーバ | 補助機能 | 診断情報（エラー・警告）の提供 |

## 機能種別

デバッグ・診断機能

## 入力仕様

### 入力パラメータ

#### debug

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --raw (-r) | switch | No | 生のValue表現を出力 | - |
| --raw-value (-v) | switch | No | 生の値部分のみを出力 | - |

#### debug info

パラメータなし

#### debug profile

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| closure | Closure | Yes | プロファイリング対象のクロージャ | - |
| --spans (-s) | switch | No | スパン情報を収集 | - |
| --expand-source (-e) | switch | No | 完全なソースフラグメントを収集 | - |
| --values (-v) | switch | No | パイプライン要素の出力値を収集 | - |
| --lines (-l) | switch | No | 行番号を収集 | - |
| --duration-values (-d) | switch | No | 実行時間をduration型で出力 | - |
| --max-depth (-m) | Int | No | ステップインする深さ（デフォルト: 2） | - |

### 入力データソース

- パイプライン入力（debugコマンド）
- クロージャ（debug profileコマンド）
- システム情報（debug infoコマンド）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| debug出力 | String/List | 値のデバッグ表現 |
| debug info出力 | Record | プロセス・システム情報 |
| debug profile出力 | Table | プロファイリング結果 |

### 出力先

標準出力（パイプライン出力）

## 処理フロー

### 処理シーケンス

```
1. debug コマンド
   └─ パイプライン入力を受け取る
   └─ フラグに応じて表現を選択
       ├─ raw: to_debug_string()
       ├─ raw-value: coerce_into_string_all() + Debug形式
       └─ 通常: to_expanded_string()

2. debug info コマンド
   └─ sysinfoでシステム情報取得
   └─ プロセス情報（メモリ、CWD、環境変数）を収集
   └─ レコード形式で返却

3. debug profile コマンド
   └─ Profilerを設定してデバッガをアクティベート
   └─ クロージャを実行
   └─ デバッガをディアクティベート
   └─ プロファイリングレポートを返却
```

### フローチャート

```mermaid
flowchart TD
    A[debug コマンド群] --> B{サブコマンド?}

    B -->|debug| C[パイプライン入力受け取り]
    C --> D{フラグ確認}
    D -->|--raw| E[to_debug_string]
    D -->|--raw-value| F[coerce_into_string_all]
    D -->|なし| G[to_expanded_string]

    B -->|debug info| H[sysinfo初期化]
    H --> I[プロセス情報取得]
    I --> J[システムメモリ情報取得]
    J --> K[レコード構築]

    B -->|debug profile| L[Profilerオプション設定]
    L --> M[デバッガアクティベート]
    M --> N[クロージャ実行]
    N --> O[デバッガディアクティベート]
    O --> P[プロファイリングレポート生成]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-74-1 | raw出力 | to_debug_string()で内部表現を出力 | --rawフラグ指定時 |
| BR-74-2 | raw-value出力 | 値部分のみをDebug形式で出力 | --raw-valueフラグ指定時 |
| BR-74-3 | プロファイル深度 | max-depthで再帰的なプロファイリングの深さを制御 | debug profile実行時 |
| BR-74-4 | 環境変数リスト化 | PATH等のパス環境変数はリスト形式で出力 | debug info実行時 |

### 計算ロジック

特になし

## データベース操作仕様

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | CantConvert | 文字列変換できない値 | エラーメッセージを返却 |
| - | GenericError | デバッガのロックエラー | Profiler Errorを返却 |

### リトライ仕様

リトライは行わない。

## トランザクション仕様

該当なし

## パフォーマンス要件

- debug profileはプロファイリングのオーバーヘッドが発生するため、本番環境での使用は推奨しない

## セキュリティ考慮事項

- debug infoはプロセスの環境変数を出力するため、機密情報が含まれる可能性がある
- プロファイリング結果にはソースコード断片が含まれる可能性がある

## 備考

- debug profileの出力カラム: depth, id, parent_id, source, pc, instruction, duration
- オプションでspan, outputカラムも追加可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

プロファイラーの設定オプションを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | profile.rs | `crates/nu-command/src/debug/profile.rs` | ProfilerOptionsの構造、DurationMode |

**読解のコツ**: ProfilerOptionsはmax_depth、collect_spans等のフラグを持ち、プロファイリングの詳細度を制御する。

#### Step 2: 各コマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | debug_.rs | `crates/nu-command/src/debug/debug_.rs` | debugコマンドの3種類の出力モード |
| 2-2 | info.rs | `crates/nu-command/src/debug/info.rs` | debug info - sysinfo連携 |
| 2-3 | profile.rs | `crates/nu-command/src/debug/profile.rs` | debug profile - Profiler連携 |

**主要処理フロー** (debug_.rs):
- **42-43行目**: raw/raw-valueフラグの取得
- **47-57行目**: 3種類の出力モードの分岐

**主要処理フロー** (info.rs):
- **56-62行目**: sysinfo初期化
- **72-80行目**: システムメモリ情報の構築
- **82-157行目**: プロセス情報の構築

**主要処理フロー** (profile.rs):
- **125-138行目**: Profilerオプションの設定
- **148-150行目**: デバッガのアクティベート
- **152行目**: クロージャの実行
- **160-164行目**: デバッガのディアクティベートとレポート取得

### プログラム呼び出し階層図

```
Debug::run (debug_.rs)
    └─ input.map()
           ├─ to_debug_string() [--raw]
           ├─ coerce_into_string_all() [--raw-value]
           └─ to_expanded_string() [通常]

DebugInfo::run (info.rs)
    └─ all_columns()
           ├─ System::new_with_specifics()
           ├─ プロセス情報取得
           └─ システム情報取得

DebugProfile::run (profile.rs)
    ├─ Profiler::new()
    ├─ engine_state.activate_debugger()
    ├─ ClosureEvalOnce::run_with_input()
    ├─ engine_state.deactivate_debugger()
    └─ debugger.report()
```

### データフロー図

```
[debug]
PipelineData ───▶ map処理 ───▶ String/List<String>

[debug info]
sysinfo ───▶ プロセス情報 ───▶ Record
         ───▶ システム情報 ───┘

[debug profile]
Closure ───▶ Profiler ───▶ 実行 ───▶ Report ───▶ Table
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| debug_.rs | `crates/nu-command/src/debug/debug_.rs` | ソース | debugコマンド |
| info.rs | `crates/nu-command/src/debug/info.rs` | ソース | debug infoコマンド |
| profile.rs | `crates/nu-command/src/debug/profile.rs` | ソース | debug profileコマンド |
| env.rs | `crates/nu-command/src/debug/env.rs` | ソース | debug envコマンド |
| mod.rs | `crates/nu-command/src/debug/mod.rs` | ソース | debugモジュール定義 |
