# 通知設計書 24-*Backtrace*表示

## 概要

本ドキュメントは、Doom Emacsにおけるバックトレース情報のポップアップ表示機能（*Backtrace*バッファ表示）の設計を定義する。

### 本通知の処理概要

*Backtrace*表示機能は、Emacs Lispの実行中にエラーが発生した際のスタックトレース（関数呼び出し履歴）を`*Backtrace*`バッファに収集し、ポップアップウィンドウとして表示する機能である。デバッグ情報としてエラー発生時の関数呼び出し階層、引数、ローカル変数等の情報を提供する。

**業務上の目的・背景**：Emacs Lisp開発やDoom Emacs設定のカスタマイズ中にエラーが発生した場合、問題の原因を特定するためにはエラー発生時のコンテキスト情報が不可欠である。バックトレースは、どの関数がどの順序で呼び出され、どこでエラーが発生したかを示す重要なデバッグ情報であり、これを適切に表示することで開発者の問題解決効率が大幅に向上する。

**通知の送信タイミング**：`debug-on-error`が有効な状態でエラーが発生した場合、またはユーザーが明示的にデバッガを起動した場合に、バックトレース情報が`*Backtrace*`バッファに表示される。

**通知の受信者**：Emacsを操作しているユーザー本人（開発者）。デバッグモードが有効な場合に表示される。

**通知内容の概要**：エラー発生時の関数呼び出しスタック、各フレームの引数、ローカル変数、発生したエラーの詳細（エラー種別とメッセージ）が構造化された形式で表示される。

**期待されるアクション**：開発者はバックトレースを分析し、エラーの原因となっている関数やコード箇所を特定する。`backtrace-mode`のコマンドを使用してフレーム間を移動し、詳細情報を確認する。問題を特定したら、該当するソースコードに移動して修正を行う。

## 通知種別

アプリ内通知（Emacsポップアップウィンドウ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 最高（:vslot 99） |
| リトライ | なし |

### 送信先決定ロジック

デバッガが起動すると`*Backtrace*`バッファが作成され、ポップアップルール `"^\\*Backtrace"` にマッチしてサイドウィンドウに表示される。

## 通知テンプレート

### ポップアップ設定

| 項目 | 内容 |
|-----|------|
| バッファ名 | `*Backtrace*` |
| :vslot | 99 |
| :size | 0.4 |
| :quit | nil |
| :select | デフォルト（ignore） |

### 本文テンプレート

```
Debugger entered--Lisp error: ({ERROR-TYPE} {ERROR-MESSAGE})
  {FUNCTION-1}({ARGS})
  {FUNCTION-2}({ARGS})
  ...
  {FUNCTION-N}({ARGS})
```

例：
```
Debugger entered--Lisp error: (void-function undefined-function)
  undefined-function()
  (progn (undefined-function))
  eval((progn (undefined-function)) t)
  elisp--eval-last-sexp(nil)
  eval-last-sexp(nil)
  funcall-interactively(eval-last-sexp nil)
  command-execute(eval-last-sexp)
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| ERROR-TYPE | エラーシンボル | error condition | Yes |
| ERROR-MESSAGE | エラーメッセージ | error data | Yes |
| FUNCTION-N | 呼び出された関数名 | backtrace-frame | Yes |
| ARGS | 関数に渡された引数 | backtrace-frame | No |
| LOCAL-VARS | ローカル変数 | 展開時に取得 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| エラー発生 | signal/error | debug-on-error = t | エラーによるデバッガ起動 |
| ユーザー操作 | debug-on-quit | C-g押下 | 中断によるデバッガ起動 |
| ユーザー操作 | M-x debug | 明示的呼び出し | 手動デバッガ起動 |
| 条件一致 | debug-on-entry | 指定関数呼び出し | 関数トレース |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| debug-on-error = nil | デバッグモード無効時 |
| inhibit-debugger = t | デバッガ抑制時 |
| noninteractive | バッチモード時 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[エラー発生/デバッガ起動] --> B{debug-on-error?}
    B -->|nil| C[エラーメッセージのみ表示]
    B -->|t| D{inhibit-debugger?}
    D -->|t| C
    D -->|nil| E[debugger関数呼び出し]
    E --> F[バックトレース収集]
    F --> G[*Backtrace*バッファ作成]
    G --> H[backtrace-mode有効化]
    H --> I[display-buffer呼び出し]
    I --> J{ポップアップルールマッチ}
    J -->|マッチ| K[ポップアップ表示]
    J -->|非マッチ| L[通常ウィンドウ表示]
    K --> M[ユーザー操作待ち]
    L --> M
    C --> N[終了]
    M --> N
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（メモリベースの処理）

### 内部変数参照

| 変数名 | 用途 | 備考 |
|--------|------|------|
| debug-on-error | デバッガ起動フラグ | t/nil/リスト |
| debug-on-quit | C-gでデバッガ起動 | t/nil |
| debugger | デバッガ関数 | デフォルトはdebug |
| backtrace-line-length | 行の最大長 | 表示フォーマット制御 |

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 再帰的エラー | デバッガ内でエラー | debugger-reenable-debugで再帰防止 |
| スタックオーバーフロー | 無限再帰 | max-lisp-eval-depthで制限 |
| バッファ作成失敗 | メモリ不足 | 最小限の情報のみ表示 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | なし |
| リトライ対象エラー | なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし

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

- バックトレースにはソースコードの構造、関数名、変数値が含まれる
- 機密データが引数やローカル変数として表示される可能性がある
- 画面共有やスクリーンショット時は注意が必要
- バグレポート提出時はバックトレースの内容を確認してから共有

## 備考

- `*Backtrace*`バッファは`:quit nil`で設定されており、ESC/C-gでは閉じない
- これはデバッグ作業中に誤ってバッファを閉じることを防ぐための意図的な設計
- `:size 0.4`で画面の40%を占有し、十分なバックトレース情報を表示
- `:vslot 99`は`*Warnings*`と同じレベルで、他のポップアップより優先表示
- `backtrace-mode`のキーバインドでフレームの展開/折り畳み、ソースへのジャンプが可能

---

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

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

### 推奨読解順序

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

バックトレースシステムはEmacs組み込み機能であり、Doom Emacsではポップアップルールのみカスタマイズしている。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/popup/config.el` | *Backtrace*バッファのポップアップルール定義 |

**読解のコツ**: `set-popup-rules!`内の`"^\\*Backtrace"`パターンを探す。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/popup/config.el` | ポップアップルールの定義箇所 |

**主要処理フロー**:
1. **163行目**: `("^\\*Backtrace" :vslot 99 :size 0.4 :quit nil)` - ルール定義
2. vslot 99は最前面表示を意味する
3. size 0.4は画面の40%を占有
4. quit nilはESC/C-gで閉じないことを意味する

#### Step 3: ポップアップクローズ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | popup.el | `modules/ui/popup/autoload/popup.el` | +popup--kill-buffer関数 |

**主要処理フロー**:
- **13-37行目**: `+popup--kill-buffer`関数でバッファとプロセスの終了処理
- **27-31行目**: debuggerバックトレースバッファでの`top-level`呼び出しを無視するハック

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

```
エラー発生/signal
    │
    └─ debugger (Emacs組み込み)
           │
           ├─ backtrace収集
           │
           └─ *Backtrace* バッファ作成
                  │
                  └─ display-buffer
                         │
                         └─ +popup--display-buffer-alist
                                │
                                └─ "^\\*Backtrace" ルールマッチ
                                       │
                                       └─ ポップアップ表示
                                              (:vslot 99, :size 0.4, :quit nil)
```

### データフロー図

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

エラー/シグナル ───▶ debugger関数 ──────▶ *Backtrace*バッファ
       │                   │
       │                   ▼
       │           backtrace収集
       │                   │
       │                   ▼
       │           バッファ作成
       │                   │
       │                   ▼
       │          backtrace-mode有効化
       │                   │
       │                   ▼
       │           display-buffer
       │                   │
       │                   ▼
       └──▶ ポップアップルール適用
                           │
                           ▼
                  vslot 99でポップアップ表示
                    (quit nil: 閉じない)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/popup/config.el` | ソース | *Backtrace*のポップアップルール定義 |
| popup.el | `modules/ui/popup/autoload/popup.el` | ソース | ポップアップ表示処理、top-levelハック |
| settings.el | `modules/ui/popup/autoload/settings.el` | ソース | :quitパラメータの処理 |
