# 機能設計書 26-ncm2連携

## 概要

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

### 本機能の処理概要

ncm2（nvim-completion-manager 2）は、NeoVim/Vim8向けの高速な補完フレームワークである。space-vimでは、+completion/auto-completionレイヤーを通じてncm2を統合し、多様な補完ソースからの候補を統一的に管理・表示する。

**業務上の目的・背景**：開発者は複数の補完ソース（バッファ、ファイルパス、言語サーバー、スニペット等）を併用することが多い。ncm2はこれらの補完ソースを統一的に管理し、ファジーマッチングによる柔軟な補完を提供する。また、NeoVim 0.2.2以降の浮動ウィンドウ機能を活用したプレビュー表示も可能。

**機能の利用シーン**：
- コード入力中に自動で補完候補を表示
- 複数の補完ソースからの候補を統合表示
- ファジーマッチングによる柔軟な候補絞り込み
- UltiSnipsと連携したスニペット補完

**主要な処理内容**：
1. +completion/auto-completionレイヤー有効化時にプラグインを登録
2. 各バッファでncm2を有効化（autocmd CursorHold,InsertEnter）
3. abbrfuzzyマッチャーを設定
4. 浮動ウィンドウプレビュー（対応環境のみ）

**関連システム・外部連携**：
- ncm2/ncm2 プラグイン
- 各種補完ソース（ncm2-bufword, ncm2-path, ncm2-jedi等）
- UltiSnips（ncm2-ultisnips）
- float-preview.nvim（浮動ウィンドウ対応時）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | 補完ポップアップ | 主機能 | ncm2による補完候補の表示 |

## 機能種別

コード補完 / 非同期処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:spacevim_use_ncm2 | Number | No | ncm2強制使用フラグ | 0/1 |
| g:ncm2#matcher | String | No | マッチャー | デフォルト: abbrfuzzy |

### 入力データソース

- ユーザー入力（キー入力）
- 各補完ソース
- バッファ内容

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 補完候補リスト | List | 補完候補の一覧 |
| ポップアップメニュー | UI | 補完候補表示UI |
| 浮動ウィンドウプレビュー | UI | 候補詳細プレビュー |

### 出力先

- Vimポップアップメニュー
- 浮動ウィンドウ（対応環境のみ）

## 処理フロー

### 処理シーケンス

```
1. +completion/auto-completionレイヤー読み込み
   └─ packages.vimで環境判定・プラグイン登録
2. autocmdでncm2有効化
   └─ CursorHold/InsertEnterで各バッファにncm2有効化
3. ユーザー入力
   └─ キー入力で補完トリガー
4. 補完候補取得
   └─ 各補完ソースから候補を収集
5. ファジーマッチング
   └─ abbrfuzzyマッチャーで候補絞り込み
6. ポップアップ表示
   └─ 補完候補をポップアップで表示
```

### フローチャート

```mermaid
flowchart TD
    A[Vim起動] --> B[+completion/auto-completionレイヤー読み込み]
    B --> C{NeoVim 0.2.2以降 & Python3?}
    C -->|Yes| D[ncm2プラグイン登録]
    C -->|No| E{Vim8?}
    E -->|Yes| F[completor.vim登録]
    E -->|No| G[vim-mucomplete登録]
    D --> H{nvim_open_win存在?}
    H -->|Yes| I[float-preview.nvim追加]
    H -->|No| J[浮動ウィンドウなし]
    I --> K[autocmd設定]
    J --> K
    K --> L[ユーザー入力待ち]
    L --> M[ncm2#enable_for_buffer]
    M --> N[補完候補取得]
    N --> O[abbrfuzzyマッチング]
    O --> P[ポップアップ表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-26-01 | 環境判定 | NeoVim 0.2.2以降+Python3でncm2、Vim8でcompletorにフォールバック | プラグイン登録時 |
| BR-26-02 | ファジーマッチ | abbrfuzzyマッチャーを使用 | 常時 |
| BR-26-03 | UltiSnips連携 | code-snippetsレイヤー有効時はncm2-ultisnips追加 | 常時 |

### 計算ロジック

なし

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

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

データベース操作なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E-26-01 | 環境不適合 | NeoVim 0.2.2未満 | completor/mucompleにフォールバック |

### リトライ仕様

なし

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

該当なし

## パフォーマンス要件

- 非同期処理により編集をブロックしない
- ファジーマッチングで高速候補絞り込み

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

なし

## 備考

- NeoVim 0.2.2以降+Python3が必要
- Vim8ではcompletorにフォールバック
- 浮動ウィンドウプレビューはnvim_open_win対応環境のみ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+completion/auto-completion/packages.vim` | 環境分岐とプラグイン登録 |

**読解のコツ**: 環境条件（NeoVim/Vim8/Python3）でプラグイン構成が変わる。

**主要処理フロー**:
- **4行目**: `has("nvim-0.2.2") && has('python3')` でncm2対応判定
- **5-17行目**: ncm2と各補完ソースのリスト定義
- **18-20行目**: Vim8用にvim-hug-neovim-rpc追加
- **21-23行目**: nvim_open_win存在時にfloat-preview.nvim追加
- **24-26行目**: code-snippetsレイヤー有効時にncm2-ultisnips追加
- **28行目**: `ncm2#enable_for_buffer()` autocmd設定
- **29行目**: `g:ncm2#matcher = 'abbrfuzzy'` マッチャー設定
- **31-35行目**: Vim8用にcompletorにフォールバック
- **38行目**: その他環境用にvim-mucomplete

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.vim | `layers/+completion/auto-completion/config.vim` | 補完設定 |

**主要処理フロー**:
- **3-13行目**: vim-mucomplete設定（フォールバック用）
- **16行目**: `completeopt=noinsert,menuone,noselect` 設定
- **18-20行目**: Tab/S-Tab/CRキーマッピング

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

```
spacevim#bootstrap()
    │
    ├─ layers/+completion/auto-completion/packages.vim
    │      ├─ 環境判定（NeoVim/Vim8/Python3）
    │      ├─ ncm2/ncm2 登録
    │      ├─ 各補完ソース登録
    │      │      ├─ ncm2-bufword
    │      │      ├─ ncm2-path
    │      │      ├─ ncm2-jedi
    │      │      └─ ...
    │      └─ autocmd CursorHold,InsertEnter
    │
    └─ layers/+completion/auto-completion/config.vim
           └─ completeopt設定、キーマッピング
```

### データフロー図

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

キー入力 ───▶ ncm2 ───▶ 各補完ソース ───▶ 補完候補
                │                              │
                ▼                              ▼
       abbrfuzzyマッチング ───────────▶ ポップアップ表示
                                              │
                                              ▼
                                    float-preview（対応時）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+completion/auto-completion/packages.vim` | ソース | プラグイン登録・環境分岐 |
| config.vim | `layers/+completion/auto-completion/config.vim` | ソース | 補完設定 |
| complete.vim | `core/autoload/spacevim/vim/complete.vim` | ソース | キーマッピング関数 |
