# 通知設計書 19-言語ユーティリティエラー通知

## 概要

本ドキュメントは、space-vimの言語ユーティリティ機能（spacevim#lang#util）において、LSP処理でエラーが発生した場合や対象が見つからなかった場合に表示されるエラー通知の設計を記載する。

### 本通知の処理概要

言語ユーティリティエラー通知は、LSP（Language Server Protocol）を使用した言語機能（定義ジャンプ、ドキュメントシンボル取得など）の処理中にエラーが発生した場合に、ユーザーにエラー内容を通知する機能である。

**業務上の目的・背景**：LSPを使用した高度な言語機能は、Language Serverの状態やコードの状況によって失敗することがある。この通知により、開発者はなぜ機能が動作しなかったかを把握でき、適切な対処（Language Serverの再起動、コードの修正など）を行うことができる。

**通知の送信タイミング**：LSP操作（定義ジャンプ、ドキュメントシンボル取得など）が失敗した場合、またはunknown LSP engineが指定された場合にspacevim#util#err関数を通じてエラーメッセージが表示される。

**通知の受信者**：Vim/NeoVimを使用しているspace-vimユーザー。ErrorMsgハイライトグループを使用して赤色でメッセージが表示される。

**通知内容の概要**：「Unknown LSP engine」「fail to go to definition via coc」「fail to get Document Symbols via coc」などのエラーメッセージが、[space-vim]プレフィックス付きで表示される。

**期待されるアクション**：開発者はエラーメッセージを確認し、Language Serverの状態を確認する、別のLSPエンジンを試す、またはコードの問題を修正する。

## 通知種別

Vimエラーメッセージ通知（ErrorMsgハイライト）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高 |
| リトライ | 無し |

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

現在アクティブなVim/NeoVimのエコーエリアに出力される。ErrorMsgハイライトグループにより赤色で強調表示される。

## 通知テンプレート

### Vimエラーメッセージの場合

| 項目 | 内容 |
|-----|------|
| 出力先 | Vimエコーエリア |
| 形式 | ErrorMsgハイライト付きテキスト |

### 本文テンプレート

```
[space-vim] ${エラーメッセージ}
```

### エラーメッセージ例

| メッセージ | 発生条件 |
|----------|---------|
| Unknown LSP engine | s:engine が 'coc' でも 'lcn' でもない場合 |
| fail to go to definition via coc | coc.nvimで定義ジャンプに失敗した場合 |
| fail to get Document Symbols via coc | coc.nvimでドキュメントシンボル取得に失敗した場合 |

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| エラーメッセージ | 固定文字列 | 関数内で定義 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | s:dispatch呼び出し | s:engine が 'coc' でも 'lcn' でもない場合 | 22-24行目 |
| 非同期コールバック | s:DefinitionCb | a:error が空でない場合 | 117-118行目 |
| 非同期コールバック | s:DocumentSymbolsCb | a:error が空でない場合 | 54-56行目 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| エラーなし | LSP操作が正常に完了した場合 |
| 有効なLSPエンジン | s:engine が 'coc' または 'lcn' の場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[LSP操作呼び出し] --> B{s:engine判定}
    B -->|coc| C[CocAction呼び出し]
    B -->|lcn| D[LanguageClient呼び出し]
    B -->|その他| E[spacevim#util#err 'Unknown LSP engine']
    C --> F{結果判定}
    F -->|成功| G[正常終了]
    F -->|失敗| H[spacevim#util#err 'fail to...']
    D --> G
```

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

### 参照テーブル一覧

該当なし（Vimバッファベースの処理）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| Unknown LSP engine | g:spacevim_lsp_engine が無効な値 | .spacevimでLSPエンジンを正しく設定 |
| 定義ジャンプ失敗 | coc.nvimが定義を見つけられない | コードの問題確認、Language Server再起動 |
| ドキュメントシンボル取得失敗 | coc.nvimがシンボルを取得できない | Language Server再起動 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（関数呼び出し時に即座に出力）

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

- 機密情報は含まれない（エラー種別のみ）
- 外部通信なし（LSP通信はLanguage Serverが行う）
- ユーザー入力は処理されない

## 備考

- 関数は`core/autoload/spacevim/lang/util.vim`で定義
- spacevim#util#err関数を使用してErrorMsgハイライトで表示
- s:engine変数は`g:spacevim_lsp_engine`から取得（1行目）
- coc.nvimとLanguageClient-neovim（LCN）の両方をサポート

---

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

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

### 推奨読解順序

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

LSPエンジン設定を保持する変数`s:engine`を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | util.vim | `core/autoload/spacevim/lang/util.vim` | s:engine変数の初期化（1行目） |
| 1-2 | util.vim | `core/autoload/spacevim/util.vim` | spacevim#util#err関数（4-8行目） |

**読解のコツ**: `g:spacevim_lsp_engine`でLSPエンジン（'coc'または'lcn'）を指定。s:dispatch関数でエンジンに応じた処理を振り分ける。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | util.vim | `core/autoload/spacevim/lang/util.vim` | s:dispatch関数（16-29行目） |

**主要処理フロー**:
1. **17行目**: `if a:0 == 2` - 引数が2つあることを確認
2. **18-21行目**: エンジンに応じたコマンド文字列生成
3. **22-24行目**: 不明なエンジンの場合エラー通知

#### Step 3: エラー通知箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | util.vim | `core/autoload/spacevim/lang/util.vim` | s:dispatch内エラー（23行目） |
| 3-2 | util.vim | `core/autoload/spacevim/lang/util.vim` | s:DocumentSymbolsCb内エラー（55行目） |
| 3-3 | util.vim | `core/autoload/spacevim/lang/util.vim` | s:DefinitionCb内エラー（118行目） |

**主要処理フロー**:
- **23行目**: `call spacevim#util#err('Unknown LSP engine')`
- **55行目**: `call spacevim#util#err('fail to get Document Symbols via coc')`
- **118行目**: `call spacevim#util#err('fail to go to definition via coc')`

#### Step 4: spacevim#util#err関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | util.vim | `core/autoload/spacevim/util.vim` | err関数定義（4-8行目） |

**主要処理フロー**:
- **5行目**: `echohl ErrorMsg` - エラーメッセージハイライト設定
- **6行目**: `call spacevim#vim#cursor#TruncatedEcho('[space-vim] '.a:msg)` - メッセージ出力
- **7行目**: `echohl None` - ハイライトリセット

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

```
LSP機能呼び出し (例: spacevim#lang#util#Definition)
    |
    +-- s:dispatch (16-29行目)
    |       |
    |       +-- if s:engine == 'coc'
    |       |       +-- CocAction/CocActionAsync
    |       |
    |       +-- elseif s:engine == 'lcn'
    |       |       +-- LanguageClient#...
    |       |
    |       +-- else
    |               +-- spacevim#util#err('Unknown LSP engine')
    |
    +-- s:DefinitionCb / s:DocumentSymbolsCb (非同期コールバック)
            |
            +-- if !empty(a:error)
                    +-- spacevim#util#err('fail to...')
```

### データフロー図

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

LSP操作要求 ──▶ s:engine判定 ──▶ エラー発生 ──▶ spacevim#util#err
                    |                              |
              'coc'/'lcn'/その他            ErrorMsgハイライト
                    |                              |
              CocAction等の呼び出し        [space-vim] エラーメッセージ
                    |
              非同期コールバック
                    |
              エラー判定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| util.vim | `core/autoload/spacevim/lang/util.vim` | ソース | 言語ユーティリティ機能の実装 |
| util.vim | `core/autoload/spacevim/util.vim` | ソース | 基本ユーティリティ（err関数など） |
| cursor.vim | `core/autoload/spacevim/vim/cursor.vim` | ソース | TruncatedEcho関数の実装 |
