# 通知設計書 21-PLUGIN_RUNTIME_ERROR

## 概要

本ドキュメントは、Lua Language Serverにおけるプラグイン実行時エラー通知（PLUGIN_RUNTIME_ERROR）の設計について記述する。

### 本通知の処理概要

この通知は、ユーザーが設定したプラグインの実行中にエラーが発生した際に、エディタのUI上にエラーメッセージを表示する機能を提供する。

**業務上の目的・背景**：Lua Language Serverはプラグイン機構を備えており、ユーザーはカスタムプラグインを作成して言語サーバーの機能を拡張できる。しかし、プラグインコードに問題がある場合、実行時にエラーが発生する可能性がある。この通知により、ユーザーはプラグインの問題を迅速に認識し、プラグイン作成者に報告するか自身で修正することができる。

**通知の送信タイミング**：プラグインのイベントディスパッチ処理（OnSetText、OnTransformAst、ResolveRequireなど）においてxpcallでエラーが捕捉された時点で送信される。同一セッション内で一度エラーが表示されると、それ以降の同種のエラーは抑止される（`_hasShowedError`フラグによる制御）。

**通知の受信者**：エディタを使用しているユーザー（開発者）。LSPクライアント経由でwindow/showMessage通知として受信する。

**通知内容の概要**：エラーが発生したプラグインのパスと、発生したエラーの内容が通知メッセージに含まれる。ユーザーに対して出力やログを確認するよう案内する。

**期待されるアクション**：ユーザーはエラーメッセージを確認し、必要に応じてプラグインの修正を行うか、プラグイン作成者に問題を報告することが期待される。

## 通知種別

LSP window/showMessage通知（エディタ内ダイアログ/通知パネル）

## 送信仕様

### 基本情報

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

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

LSPクライアント（エディタ）に対してwindow/showMessage通知を送信する。受信者はエディタを操作しているユーザー。

## 通知テンプレート

### LSP通知の場合

| 項目 | 内容 |
|-----|------|
| 通知タイプ | window/showMessage |
| メッセージタイプ | Error（1） |
| 件名 | なし（LSP仕様） |

### 本文テンプレート

英語版:
```
An error occurred in the plugin, please report it to the plugin author.
Please check the details in the output or log.
Plugin path: {pluginPath}
```

日本語版:
```
プラグインの実行中にエラーが発生しました。プラグイン作成者に報告してください。
詳細は出力またはログ画面でご確認ください。
プラグインのパス：{pluginPath}
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| pluginPath | プラグインファイルのパス | scp:get('pluginPath') | Yes |
| err | エラー内容 | xpcallの戻り値 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| プラグインイベント | plugin.dispatch実行時 | xpcallでエラー捕捉 && !m._hasShowedError | プラグインメソッド呼び出し時のエラー |
| プラグイン初期化 | initPlugin実行時 | loadまたはxpcallでエラー捕捉 | プラグインのロードまたは初期実行時のエラー |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| m._hasShowedError == true | 同一セッション内で既にエラー通知が表示済みの場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[プラグインイベント発生] --> B[plugin.dispatch呼び出し]
    B --> C[xpcallでメソッド実行]
    C -->|成功| D[正常終了]
    C -->|失敗| E{_hasShowedError?}
    E -->|Yes| F[エラー通知スキップ]
    E -->|No| G[m.showError呼び出し]
    G --> H[_hasShowedError = true]
    H --> I[client.showMessage実行]
    I --> J[window/showMessage通知送信]
    J --> K[window/logMessage通知送信]
```

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

### 参照テーブル一覧

データベースは使用しない（インメモリ処理のみ）。

### テーブル別参照項目詳細

該当なし

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| プラグインロードエラー | プラグインファイルが見つからない | ログに警告を出力、処理を中断 |
| プラグイン構文エラー | load関数でエラー | showErrorでユーザーに通知 |
| プラグイン実行時エラー | xpcallでエラー捕捉 | showErrorでユーザーに通知 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1セッションあたり上限 | 1回（_hasShowedErrorフラグで制御） |

### 配信時間帯

制限なし（エラー発生時即座に通知）

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

- プラグインパスにはユーザーのローカルファイルシステムのパスが含まれる可能性があるが、ユーザー本人への通知のためセキュリティリスクは低い
- エラー内容にはスタックトレースが含まれる可能性があるが、同様にユーザー本人への通知のため問題なし

## 備考

- プラグインシステムの詳細については機能設計書「77-プラグインシステム」を参照
- エラー通知は同一セッション内で一度のみ表示される設計となっている

---

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

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

### 推奨読解順序

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

プラグインモジュールの構造とスコープの関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | plugin.lua | `script/plugin.lua` | プラグインモジュールの全体構造、m._hasShowedErrorフラグの役割 |

**読解のコツ**: Luaのモジュールパターン（local m = {}で始まりreturn mで終わる）を理解すること。

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

エラー通知のトリガーとなる関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | plugin.lua | `script/plugin.lua` | m.showError関数（13-19行目）の実装 |
| 2-2 | plugin.lua | `script/plugin.lua` | m.dispatch関数（24-52行目）でのエラー捕捉処理 |

**主要処理フロー**:
1. **13行目**: showError関数の定義開始
2. **14-16行目**: _hasShowedErrorフラグのチェックと設定
3. **18行目**: client.showMessageの呼び出し
4. **40行目**: xpcallによるプラグインメソッド呼び出し
5. **46-48行目**: エラー時のshowError呼び出し

#### Step 3: クライアント通知層を理解する

LSPクライアントへの通知送信処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | client.lua | `script/client.lua` | showMessage関数（102-113行目）の実装 |

**主要処理フロー**:
- **102行目**: showMessage関数の定義
- **104-107行目**: window/showMessage通知の送信
- **108-111行目**: window/logMessage通知の送信

#### Step 4: ローカライズ層を理解する

メッセージテンプレートの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | script.lua | `locale/en-us/script.lua` | PLUGIN_RUNTIME_ERROR定義（643-648行目） |
| 4-2 | script.lua | `locale/ja-jp/script.lua` | 日本語版メッセージ定義（643-648行目） |

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

```
plugin.dispatch (script/plugin.lua:24)
    │
    ├─ xpcall (Lua標準) - プラグインメソッド実行
    │      │
    │      └─ [エラー発生時]
    │              │
    │              └─ plugin.showError (script/plugin.lua:13)
    │                      │
    │                      └─ client.showMessage (script/client.lua:102)
    │                              │
    │                              ├─ proto.notify('window/showMessage')
    │                              │
    │                              └─ proto.notify('window/logMessage')
    │
    └─ initPlugin (script/plugin.lua:94)
           │
           ├─ load (Lua標準) - プラグインコードのロード
           │      │
           │      └─ [エラー発生時] → plugin.showError
           │
           └─ xpcall (Lua標準) - プラグイン初期化実行
                  │
                  └─ [エラー発生時] → plugin.showError
```

### データフロー図

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

プラグイン       ───▶  plugin.dispatch         ───▶  正常終了
イベント                    │                              or
                           ▼                         エラー通知
                    xpcall(method)
                           │
                           ▼ [エラー]
                    plugin.showError
                           │
                           ▼
                    client.showMessage
                           │
                           ▼
                    proto.notify ───────────────▶  LSPクライアント
                                                   (エディタ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| plugin.lua | `script/plugin.lua` | ソース | プラグインシステムの中核、エラー通知のトリガー |
| client.lua | `script/client.lua` | ソース | LSPクライアント通信、showMessage実装 |
| proto.lua | `script/proto/proto.lua` | ソース | LSPプロトコル通信基盤 |
| script.lua | `locale/en-us/script.lua` | ローカライズ | 英語メッセージ定義 |
| script.lua | `locale/ja-jp/script.lua` | ローカライズ | 日本語メッセージ定義 |
| language.lua | `script/language.lua` | ソース | ローカライズ機能 |
