# 通知設計書 23-*Warnings*表示

## 概要

本ドキュメントは、Doom Emacsにおける警告メッセージのポップアップ表示機能（*Warnings*バッファ表示）の設計を定義する。

### 本通知の処理概要

*Warnings*表示機能は、Emacsシステムやパッケージが発する警告メッセージを専用の`*Warnings*`バッファに収集し、ポップアップウィンドウとして表示する機能である。設定エラー、非推奨機能の使用、互換性の問題など、ユーザーが対処すべき警告情報を視覚的に通知する。

**業務上の目的・背景**：Emacsの設定やパッケージ利用中に発生する警告は、放置すると予期せぬ動作や将来的な互換性問題につながる可能性がある。これらの警告を見逃さず、適切なタイミングでユーザーに通知することで、問題の早期発見と対処が可能になる。特にDoom Emacsでは多数のパッケージが連携して動作するため、設定の不整合や非推奨機能の使用を早期に把握することが重要である。

**通知の送信タイミング**：`lwarn`関数や`display-warning`関数が呼び出された時点で、警告レベルに応じて`*Warnings*`バッファに内容が追加され、ポップアップとして表示される。

**通知の受信者**：Emacsを操作しているユーザー本人。警告はユーザーの現在のフレーム内にポップアップとして表示される。

**通知内容の概要**：警告の種別（type）、レベル（:warning, :error等）、メッセージ本文が表示される。フックエラーやパッケージの問題など、システムが検出した問題の詳細が含まれる。

**期待されるアクション**：ユーザーは警告内容を確認し、必要に応じて設定ファイルの修正、パッケージのアップデート、または問題の調査を行う。緊急性の低い警告は確認後にポップアップを閉じ、重大な警告については根本原因を解決する。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

警告が発生すると`*Warnings*`バッファが作成または更新され、ポップアップルール `"^\\*Warnings"` にマッチしてサイドウィンドウに表示される。

## 通知テンプレート

### ポップアップ設定

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

### 本文テンプレート

```
Warning ({TYPE}): {MESSAGE}
```

例：
```
Warning (initialization): An error occurred while loading '/Users/user/.doom.d/config.el':

Symbol's function definition is void: some-undefined-function
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| TYPE | 警告の種別 | lwarn/display-warning第1引数 | Yes |
| LEVEL | 警告レベル | :warning/:error等 | Yes |
| MESSAGE | 警告メッセージ本文 | lwarn/display-warning第2引数以降 | Yes |
| TIMESTAMP | 発生時刻 | current-time（表示オプション） | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | lwarn | 警告レベルが閾値以上 | 構造化された警告発行 |
| 関数呼び出し | display-warning | 警告レベルが閾値以上 | 汎用警告表示 |
| 関数呼び出し | warn | 常時 | 簡易警告メッセージ |
| フックエラー | doom-run-hook-on | エラー発生時 | フック実行時のエラー警告 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| warning-minimum-level | 設定された最小レベル未満の警告は抑止 |
| warning-suppress-types | 指定された種別の警告は抑止 |
| noninteractive | 非対話モードでは表示方法が異なる |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[lwarn/display-warning呼び出し] --> B{警告レベルチェック}
    B -->|閾値未満| C[抑止]
    B -->|閾値以上| D{種別チェック}
    D -->|抑止対象| C
    D -->|表示対象| E[*Warnings*バッファ作成/更新]
    E --> F[display-buffer呼び出し]
    F --> G{ポップアップルールマッチ}
    G -->|マッチ| H[ポップアップ表示]
    G -->|非マッチ| I[通常ウィンドウ表示]
    H --> J[ユーザー確認待ち]
    I --> J
    C --> K[終了]
    J --> K
```

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

### 参照テーブル一覧

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

### 内部変数参照

| 変数名 | 用途 | 備考 |
|--------|------|------|
| warning-minimum-level | 表示する最小警告レベル | :debug, :warning, :error |
| warning-suppress-types | 抑止する警告種別リスト | リスト形式 |
| warning-type-format | 警告種別の表示フォーマット | 文字列 |

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| バッファ作成失敗 | メモリ不足 | エラーをメッセージ領域に表示 |
| フォーマットエラー | 不正なformat文字列 | エラー情報をそのまま表示 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし

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

- 警告メッセージにはファイルパスや設定内容が含まれる可能性があるため、画面共有時は注意
- スタックトレースには内部情報が含まれる場合がある

## 備考

- `*Warnings*`バッファは`:vslot 99`で他のポップアップより上位に表示される
- `:quit t`により、ESC/C-gで閉じることが可能
- `:select`はデフォルトでignoreのため、警告表示時にフォーカスは移動しない
- Doom Emacsでは`doom-hook-error警告`（通知No.3）と連携してフックエラーを報告

---

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

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

### 推奨読解順序

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

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

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

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

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

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

**主要処理フロー**:
1. **162行目**: `("^\\*Warnings" :vslot 99 :size 0.25)` - ルール定義
2. vslot 99は最前面表示を意味する
3. size 0.25は画面の25%を占有

#### Step 3: 警告発行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | doom-lib.el | `lisp/doom-lib.el` | doom-run-hook-onでのエラーハンドリング |

**主要処理フロー**:
- Doom Emacsの各種フックでエラーが発生した場合、`lwarn`で警告が発行される
- これにより`*Warnings*`バッファに警告が蓄積される

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

```
lwarn / display-warning (Emacs組み込み)
    │
    └─ warnings.el (Emacs)
           │
           ├─ warning-minimum-level チェック
           │
           ├─ warning-suppress-types チェック
           │
           └─ *Warnings* バッファ作成/更新
                  │
                  └─ display-buffer
                         │
                         └─ +popup--display-buffer-alist
                                │
                                └─ "^\\*Warnings" ルールマッチ
                                       │
                                       └─ ポップアップ表示
                                              (:vslot 99, :size 0.25)
```

### データフロー図

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

警告発生 ─────────▶ lwarn/display-warning ───▶ *Warnings*バッファ
   │                       │
   │                       ▼
   │              レベル/種別チェック
   │                       │
   │              ┌────────┴────────┐
   │              ▼                 ▼
   │         表示対象           抑止対象
   │              │                 │
   │              ▼                 ▼
   │        バッファ追記          終了
   │              │
   │              ▼
   │        display-buffer
   │              │
   │              ▼
   └─▶ ポップアップルール適用
                  │
                  ▼
         vslot 99でポップアップ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/popup/config.el` | ソース | *Warnings*のポップアップルール定義 |
| doom-lib.el | `lisp/doom-lib.el` | ソース | フックエラー時のlwarn呼び出し |
| popup.el | `modules/ui/popup/autoload/popup.el` | ソース | ポップアップ表示処理 |
