# 機能設計書 29-coc.nvim連携

## 概要

本ドキュメントは、space-vimにおけるcoc.nvim連携機能の設計仕様を定義する。

### 本機能の処理概要

coc.nvim（Conquer of Completion）は、VS Code互換のLSPサポートを提供するVim/NeoVim向けプラグインである。space-vimでは、+tools/lspレイヤーを通じてcoc.nvimを統合し、多言語に対応したIntelliSense機能（補完、診断、定義ジャンプ、リファクタリング等）を提供する。

**業務上の目的・背景**：Language Server Protocol（LSP）の普及により、エディタと言語サーバーの分離が進んでいる。coc.nvimはVS Code拡張機能と互換性があり、豊富なエコシステムを活用できる。また、Node.jsベースの実装により、高速な非同期処理と豊富な機能を提供する。

**機能の利用シーン**：
- 多言語でのLSPベースの補完、診断、定義ジャンプ
- VS Code拡張機能（coc extensions）の利用
- シンボルハイライト、シグネチャヘルプ
- コードアクション、フォーマット

**主要な処理内容**：
1. +tools/lspレイヤーでg:spacevim_lsp_engine='coc'設定時にプラグインを登録
2. 遅延読み込み（timer 200ms）でcoc.nvimを初期化
3. Tab/Shift-Tab/CRキーマッピング、K（ドキュメント表示）を設定
4. CursorHoldでシンボルハイライト

**関連システム・外部連携**：
- neoclide/coc.nvim プラグイン
- Node.js（必須）
- coc extensions（coc-neco等）
- Language Servers

**権限による制御**：特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | 補完ポップアップ | 関連機能 | coc.nvimによる補完候補の表示 |
| 9 | LSP診断画面 | 主機能 | coc.nvimによるLSPエラー・警告の表示 |

## 機能種別

コード補完 / LSP連携 / 診断

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:spacevim_lsp_engine | String | No | LSPエンジン選択 | coc / vim_lsp / lcn |
| cmdheight | Number | No | コマンドライン高さ | デフォルト: 2 |
| updatetime | Number | No | CursorHold遅延 | デフォルト: 300 |

### 入力データソース

- ユーザー入力（キー入力）
- Language Server
- coc extensions

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 補完候補リスト | List | 補完候補の一覧 |
| 診断情報 | List | エラー/警告情報 |
| ホバー情報 | String | シンボル情報 |
| シグネチャヘルプ | String | 関数シグネチャ |

### 出力先

- Vimポップアップメニュー
- サインカラム
- フローティングウィンドウ

## 処理フロー

### 処理シーケンス

```
1. +tools/lspレイヤー読み込み
   └─ packages.vimでcoc.nvimプラグイン登録
2. 遅延読み込み（200ms後）
   └─ spacevim#plug#coc#Init()で初期化
3. config.vim実行
   └─ キーマッピング、オプション設定
4. CocNvimInit発火
   └─ coc.nvim完全初期化
5. ユーザー操作
   └─ 補完、診断、定義ジャンプ等
```

### フローチャート

```mermaid
flowchart TD
    A[Vim起動] --> B[+tools/lspレイヤー読み込み]
    B --> C{g:spacevim_lsp_engine?}
    C -->|coc| D[coc.nvimプラグイン登録]
    C -->|vim_lsp| E[vim-lsp登録]
    C -->|lcn| F[LanguageClient-neovim登録]
    D --> G[timer_start 200ms]
    G --> H[spacevim#plug#coc#Init]
    H --> I{NeoVim?}
    I -->|No| J[coc#rpc#start_server]
    I -->|Yes| K[直接初期化]
    J --> L[doautocmd CocNvimInit]
    K --> L
    L --> M[config.vim設定適用]
    M --> N[キーマッピング設定]
    N --> O[autocmd設定]
    O --> P[ユーザー操作待ち]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-29-01 | LSPエンジン選択 | g:spacevim_lsp_engineでcoc/vim_lsp/lcnから選択 | プラグイン登録時 |
| BR-29-02 | シンボルハイライト | CursorHoldでカーソル位置のシンボルをハイライト | 常時 |
| BR-29-03 | Kキードキュメント | Vimファイルでは:help、それ以外はdoHover | 常時 |

### 計算ロジック

なし

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

### 操作別データベース影響一覧

データベース操作なし

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E-29-01 | Node.js未検出 | Node.jsがインストールされていない | インストールを促すメッセージ |
| E-29-02 | LSサーバー未起動 | Language Serverが起動しない | エラーメッセージ表示 |

### リトライ仕様

なし

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

該当なし

## パフォーマンス要件

- 遅延読み込みにより起動時間を最適化（200ms後にロード）
- updatetime=300で高速なCursorHold反応

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

なし

## 備考

- Node.js必須
- VS Code拡張機能と互換性あり
- coc extensionsで機能拡張可能

---

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

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

### 推奨読解順序

#### Step 1: プラグイン登録を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+tools/lsp/packages.vim` | LSPエンジン選択とプラグイン登録 |

**読解のコツ**: s:{g:spacevim_lsp_engine}()で動的に関数を呼び出す。

**主要処理フロー**:
- **1-9行目**: `s:coc()` - coc.nvim登録、timer_start(200ms)で遅延初期化
- **7-8行目**: neco-vim/coc-neco登録（ftplugin/vim.vimでロード）
- **27行目**: `g:spacevim_lsp_engine`デフォルト値は'lcn'
- **29行目**: `s:{g:spacevim_lsp_engine}()`で動的関数呼び出し

#### Step 2: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | coc.vim | `core/autoload/spacevim/plug/coc.vim` | coc.nvim初期化 |

**主要処理フロー**:
- **1-15行目**: `spacevim#plug#coc#Init()` - タイマーコールバック
- **7-9行目**: Vim（非NeoVim）の場合はcoc#rpc#start_server()呼び出し
- **12-14行目**: CocNvimInit autocmd発火
- **18-24行目**: `spacevim#plug#coc#show_documentation()` - Kキー処理

#### Step 3: 設定処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.vim | `layers/+tools/lsp/config.vim` | LSP設定 |

**主要処理フロー**:
- **2行目**: gd（定義ジャンプ）キーマッピング
- **6行目**: set hidden（複数バッファ操作用）
- **16-57行目**: `s:coc()` - coc固有設定
- **18行目**: cmdheight=2（メッセージ表示領域拡大）
- **21行目**: updatetime=300（CursorHold高速化）
- **24行目**: signcolumn=yes（常時サインカラム表示）
- **27-28行目**: Tab/S-Tabキーマッピング
- **31行目**: Ctrl-Spaceで補完トリガー
- **43行目**: CRで補完確定
- **46行目**: Kでドキュメント表示
- **49行目**: CocJumpPlaceholderでシグネチャヘルプ
- **52行目**: CursorHoldでシンボルハイライト
- **55-56行目**: LocalLeader=でフォーマット

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

```
spacevim#bootstrap()
    │
    ├─ layers/+tools/lsp/packages.vim
    │      ├─ s:coc() / s:vim_lsp() / s:lcn()
    │      ├─ MP 'neoclide/coc.nvim'
    │      └─ timer_start(200, spacevim#plug#coc#Init)
    │
    ├─ core/autoload/spacevim/plug/coc.vim
    │      ├─ spacevim#plug#coc#Init()
    │      └─ spacevim#plug#coc#show_documentation()
    │
    └─ layers/+tools/lsp/config.vim
           └─ s:coc()設定
```

### データフロー図

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

キー入力 ───▶ coc.nvim ───▶ Language Server ───▶ 補完候補/診断
                 │                                  │
                 ▼                                  ▼
          CursorHold ───▶ highlight ───▶ シンボルハイライト
                 │                                  │
                 ▼                                  ▼
               K押下 ───▶ doHover ───▶ フローティングウィンドウ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+tools/lsp/packages.vim` | ソース | プラグイン登録 |
| config.vim | `layers/+tools/lsp/config.vim` | ソース | LSP設定 |
| coc.vim | `core/autoload/spacevim/plug/coc.vim` | ソース | coc.nvim初期化 |
| complete.vim | `core/autoload/spacevim/vim/complete.vim` | ソース | Tab関数（coc連携） |
