# 機能設計書 59-デバッガ統合（DAP）

## 概要

本ドキュメントは、Doom Emacsの`tools/debugger`モジュールが提供するデバッガ統合機能の設計仕様を記述する。dapeパッケージを使用したDebug Adapter Protocol（DAP）対応デバッガとの統合により、多言語でのグラフィカルなデバッグ環境を提供する。

### 本機能の処理概要

**業務上の目的・背景**：デバッグはソフトウェア開発において不可欠な作業である。Debug Adapter Protocol（DAP）は、VSCodeで導入された汎用デバッガプロトコルであり、多くの言語のデバッガがこのプロトコルをサポートしている。Doom Emacsでdapeを通じてDAPに対応することで、Python、JavaScript、Go、Rust、C/C++など多言語での一貫したデバッグ体験を提供する。

**機能の利用シーン**：
- ブレークポイントの設定と管理
- ステップ実行（step in/over/out）
- 変数の値の確認と変更
- コールスタックの確認
- REPL（Read-Eval-Print Loop）でのインタラクティブ評価

**主要な処理内容**：
1. dapeによるDAP対応デバッガとの通信
2. ブレークポイントの永続化
3. インレイヒントによる変数値表示
4. REPLウィンドウの管理
5. プロジェクトルートの自動検出

**関連システム・外部連携**：
- dape（DAP Emacsクライアント）
- Debug Adapter各種（Python: debugpy、Node.js: node-debug2等）
- projectile（プロジェクト管理）
- dap-mode（レガシー、+lspフラグ時）

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | ソースコードバッファ | 主画面 | ブレークポイント設定、ステップ実行 |
| - | REPL | 補助画面 | インタラクティブ評価 |
| - | 変数/スタックビュー | 補助画面 | デバッグ情報表示 |

## 機能種別

デバッグ支援 / 外部ツール連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| +lsp | flag | No | dap-modeを使用（deprecated） | modulep!でチェック |

### 入力データソース

- プロジェクトのソースコード
- Debug Adapterの設定（launch.json等）
- ブレークポイント永続化ファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 変数値 | string | インレイヒントまたはREPL出力 |
| コールスタック | list | 現在の呼び出し階層 |
| ブレークポイント | overlay | ブレークポイント位置のマーカー |

### 出力先

- ソースコードバッファ（インレイヒント）
- dape REPLバッファ
- dapeバッファ（変数、スタック等）

## 処理フロー

### 処理シーケンス

```
1. デバッグセッション開始（+debugger/start または dape）
   └─ Debug Adapter選択、設定読み込み
2. Debug Adapterとの接続
   └─ DAPプロトコルで通信開始
3. ブレークポイント設定
   └─ ソースコードにマーカー表示
4. プログラム実行
   └─ ブレークポイントで停止
5. デバッグ操作
   └─ ステップ実行、変数確認等
6. セッション終了
   └─ ブレークポイント永続化、リソース解放
```

### フローチャート

```mermaid
flowchart TD
    A[+debugger/start] --> B[Debug Adapter選択]
    B --> C[設定読み込み]
    C --> D[アダプター起動]
    D --> E[DAPハンドシェイク]
    E --> F[ブレークポイント送信]
    F --> G[プログラム実行]
    G --> H{ブレークポイント?}
    H -->|Yes| I[実行停止]
    H -->|No| J{プログラム終了?}
    J -->|No| G
    J -->|Yes| K[セッション終了]
    I --> L[デバッグ操作]
    L --> M{継続?}
    M -->|Yes| G
    M -->|No| N[+debugger/quit]
    N --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-59-01 | ウィンドウ配置 | デバッグUIは右側に配置 | dape-buffer-window-arrangement 'right |
| BR-59-02 | インレイヒント | 変数値をインレイで表示 | dape-inlay-hints t |
| BR-59-03 | ブレークポイント永続化 | セッション間でブレークポイントを保存 | dape-breakpoint-global-mode |
| BR-59-04 | CWD自動検出 | projectileまたはデフォルトCWDを使用 | +debugger-dape-cwd-function-fn |

### 計算ロジック

- プロジェクトルート: `projectile-project-root`、フォールバックは`dape--default-cwd`
- アダプターディレクトリ: `doom-user-dir/debug-adapters/`

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

本機能はデータベース操作を行わない。ファイルシステム上にブレークポイントを保存する。

### 操作別ファイル影響一覧

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ブレークポイント保存 | `dape-default-breakpoints-file` | WRITE | ブレークポイント永続化 |
| ブレークポイント読み込み | `dape-default-breakpoints-file` | READ | ブレークポイント復元 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アダプター未検出 | Debug Adapterが未インストール | エラーメッセージ表示 |
| - | 接続失敗 | DAPハンドシェイク失敗 | リトライまたはエラー表示 |
| - | セッションなし | 終了すべきセッションがない | user-error |

### リトライ仕様

接続失敗時は手動でのリトライが必要。

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

トランザクション処理は不要。

## パフォーマンス要件

- ステップ実行: 即時応答
- 変数評価: 1秒以内

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

- Debug Adapterは信頼できるソースからインストールすること
- 実行するコードのセキュリティに注意

## 備考

- +lspフラグはdap-modeを使用するが、非推奨（deprecated）
- eglotとdap-modeの同時使用は非互換（doctor.elで警告）

---

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

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

### 推奨読解順序

#### Step 1: dape基本設定を理解する

まず、dapeの基本設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/tools/debugger/config.el` | dape設定（6-33行目） |

**読解のコツ**: `dape-adapter-dir`でアダプターのインストール先を指定。

**主要処理フロー**:
1. **9行目**: アダプターディレクトリを`doom-user-dir/debug-adapters/`に設定
2. **12行目**: ウィンドウ配置を右側に設定
3. **13行目**: インレイヒントを有効化
4. **14行目**: CWD関数を設定
5. **26行目**: ブレークポイント永続化モードを有効化

#### Step 2: CWD関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/tools/debugger/config.el` | CWD関数（17-20行目） |

**主要処理フロー**:
- **18-19行目**: `projectile-project-root`を優先、フォールバックは`dape--default-cwd`

#### Step 3: コマンド定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | autoload/debugger.el | `modules/tools/debugger/autoload/debugger.el` | コマンド（4-13行目） |

**主要処理フロー**:
- **4行目**: `+debugger/start`を`dape`にエイリアス
- **7-13行目**: `+debugger/quit`でセッション終了

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

```
+debugger/start (dape)
    │
    ├─ dape-adapter-dir (アダプター検索)
    │
    ├─ +debugger-dape-cwd-function-fn
    │      │
    │      └─ projectile-project-root
    │             └─ dape--default-cwd (フォールバック)
    │
    ├─ dape--live-connection
    │
    └─ dape-breakpoint-global-mode
           │
           ├─ dape-breakpoint-save
           │
           └─ dape-breakpoint-load

+debugger/quit
    │
    └─ dape-quit (conn)
```

### データフロー図

```
[入力]               [処理]                    [出力]

ソースコード ───▶ dape ───▶ Debug Adapter
                    │              │
                    ▼              ▼
         ブレークポイント ◀── DAPプロトコル
                    │              │
                    ▼              ▼
              停止/変数値 ◀── デバッグ情報
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/tools/debugger/config.el` | ソース | メイン設定 |
| packages.el | `modules/tools/debugger/packages.el` | 設定 | 依存パッケージ定義 |
| autoload/debugger.el | `modules/tools/debugger/autoload/debugger.el` | ソース | コマンド定義 |
| doctor.el | `modules/tools/debugger/doctor.el` | 診断 | eglot互換性チェック |
