# 機能設計書 34-vim-clap連携

## 概要

本ドキュメントは、space-vimにおけるvim-clap連携機能の設計仕様を定義する。vim-clapはRustで実装された高性能なファジーファインダーであり、モダンなUI/UXとフローティングウィンドウによる検索体験を提供する。

### 本機能の処理概要

vim-clap連携機能は、fzfの代替としてRust製の高速ファジーファインダーを統合する。vim-clapはネイティブバイナリによる高速なファジーマッチングとモダンなポップアップUIを特徴とし、NeoVim/Vimの両方でフローティングウィンドウ体験を提供する。また、coc-clapとの連携によりcoc.nvimの各種機能もvim-clapインターフェースで利用可能となる。

**業務上の目的・背景**：fzfはターミナル機能に依存し、外部バイナリのインストールが必要である。vim-clapは純粋なVimプラグインとして動作しつつ、Rustによるネイティブフィルタリングで高速な検索を実現する。また、ポップアップウィンドウによるモダンなUIは、ユーザー体験の向上に寄与する。

**機能の利用シーン**：
- fzfの代替としてモダンなファジー検索を使用したい場合
- フローティングウィンドウによる検索UIを好む場合
- coc.nvimとの統合検索を行いたい場合
- Rustバイナリによる高速検索を活用したい場合

**主要な処理内容**：
1. ファイル検索（:Clap files）- カレントディレクトリ以下のファイル一覧をファジー検索
2. バッファ検索（:Clap buffers）- 開いているバッファをファジー検索
3. テキスト検索（:Clap grep2）- ripgrepによるプロジェクト内全文検索
4. 行検索（:Clap blines, :Clap lines）- バッファ内の行をファジー検索
5. コマンド履歴検索（:Clap hist:）- 過去に実行したExコマンドを検索
6. タグ検索（:Clap tags）- バッファ内タグを検索

**関連システム・外部連携**：
- vim-clap（liuchengxu/vim-clap）
- coc-clap（coc.nvimとの連携プラグイン）
- ripgrep（rg）- grep2プロバイダーで使用

**権限による制御**：特になし。すべてのユーザーが使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | FZF（ファジーファインダー） | 代替画面 | vim-clap有効時のfzf代替として検索機能を提供 |

## 機能種別

検索処理 / UI操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:spacevim_enable_clap | Number | No | vim-clap使用フラグ（1で有効） | 0 or 1 |
| g:clap_provider_quick_open | Dict | No | クイックオープン用カスタムプロバイダー | 有効なプロバイダー定義 |

### 入力データソース

- ファイルシステム（:Clap files）
- Vimバッファリスト（:Clap buffers）
- ripgrep出力（:Clap grep2）
- カレントバッファ内容（:Clap blines）
- 全バッファ内容（:Clap lines）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 選択ファイルパス | String | ユーザーが選択したファイルのパス |
| 選択行番号 | Number | テキスト検索時の行番号 |
| 選択コマンド | String | コマンド履歴から選択されたコマンド |

### 出力先

- エディタバッファ（ファイルを開く）
- コマンドライン（コマンド実行）
- カーソル位置（行ジャンプ）

## 処理フロー

### 処理シーケンス

```
1. vim-clap有効化確認
   └─ g:spacevim_enable_clap = 1 の確認
2. Clapコマンド実行
   └─ :Clap files, :Clap buffers 等のコマンド呼び出し
3. データソースの取得
   └─ 各プロバイダーによるデータ収集
4. フローティングウィンドウ表示
   └─ ポップアップウィンドウでClapインターフェース表示
5. ユーザー入力によるフィルタリング
   └─ Rustバイナリによる高速ファジーマッチング
6. 選択結果の処理
   └─ ファイルオープン、コマンド実行等
```

### フローチャート

```mermaid
flowchart TD
    A[Clapコマンド実行] --> B{g:spacevim_enable_clap?}
    B -->|0| C[fzf使用]
    B -->|1| D{Clapコマンド種別}
    D -->|files| E[ファイル一覧取得]
    D -->|buffers| F[バッファ一覧取得]
    D -->|grep2| G[ripgrep実行]
    D -->|blines| H[現在バッファの行取得]
    E --> I[Clapウィンドウ表示]
    F --> I
    G --> I
    H --> I
    I --> J[ユーザー入力待ち]
    J --> K[Rustファジーマッチング]
    K --> L[候補リスト更新]
    L --> J
    J --> M{選択/キャンセル}
    M -->|選択| N[アクション実行]
    M -->|キャンセル| O[ウィンドウ閉じる]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 明示的有効化必須 | g:spacevim_enable_clap=1で明示的に有効化が必要 | 常時 |
| BR-02 | fzf代替 | vim-clap有効時はfzfの代わりにvim-clapを使用 | g:spacevim_enable_clap=1 |
| BR-03 | バイナリ自動インストール | `:Clap install-binary!`でRustバイナリを自動インストール | プラグインロード時 |
| BR-04 | coc-clap連携 | coc.nvim使用時はcoc-clapも自動ロード | vim-clap有効時 |

### 計算ロジック

該当なし

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

該当なし（ファイルシステムベースの操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| CLAP-001 | バイナリ未インストール | Rustバイナリがビルドされていない | `:Clap install-binary!`を実行 |
| CLAP-002 | プロバイダー未定義 | カスタムプロバイダーが未設定 | プロバイダー定義を追加 |

### リトライ仕様

特になし。エラー時はメッセージを表示し、処理を中断。

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

該当なし

## パフォーマンス要件

- ファイル一覧表示: 500ms以内（Rustバイナリ使用時）
- インクリメンタル検索: 50ms以内のレスポンス
- フローティングウィンドウ表示: 100ms以内

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

- Rustバイナリのビルド・実行権限を確認
- 外部からのプロバイダー定義の検証

## 備考

- Rustバイナリのビルドにはcargo（Rustツールチェーン）が必要
- g:spacevim_enable_clap = 1 の設定が必要
- auto-pairsプラグインとの干渉に注意

---

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

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

### 推奨読解順序

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

vim-clapの有効化条件とプロバイダー構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+tools/fzf/packages.vim` | vim-clapのロード条件 |
| 1-2 | manager.vim | `core/autoload/spacevim/map/manager.vim` | s:clap_enabled変数の定義 |

**読解のコツ**: `get(g:, 'spacevim_enable_clap', 0)` でvim-clapの有効/無効を判定。デフォルトは無効（0）で、明示的に1を設定する必要がある。

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

vim-clapのプラグインロードを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | packages.vim | `layers/+tools/fzf/packages.vim` | プラグインロード |

**主要処理フロー**:
1. **1行目**: `get(g:, 'spacevim_enable_clap', 0)` 条件判定
2. **2行目**: `MP 'liuchengxu/vim-clap', { 'do': ':Clap install-binary!' }` - プラグインロードとバイナリインストール
3. **3行目**: `MP 'vn-ki/coc-clap'` - coc.nvim連携プラグイン

#### Step 3: マネージャー関数でのvim-clap分岐を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | manager.vim | `core/autoload/spacevim/map/manager.vim` | vim-clap/fzf切り替えロジック |

**主要処理フロー**:
- **1行目**: `let s:clap_enabled = get(g:, 'spacevim_enable_clap', 0)` - 有効化フラグ
- **11-14行目**: Buffers関数での分岐
  - `if s:clap_enabled && exists(':Clap')` → `Clap buffers`
- **19-22行目**: Files関数での分岐
- **48-51行目**: BLines関数での分岐
- **79-82行目**: Rg関数での分岐（`Clap grep2`）

#### Step 4: カスタムプロバイダーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | manager.vim | `core/autoload/spacevim/map/manager.vim` | quick_openプロバイダー定義 |

**主要処理フロー**:
- **123-132行目**: QuickOpen関数でのカスタムプロバイダー定義
  - `g:clap_provider_quick_open` の動的定義
  - source, sink, on_move_async の設定

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

```
<Leader>ff (キーバインド)
    │
    └─ spacevim#map#manager#Files()
           │
           ├─ [vim-clap有効時]
           │      └─ :Clap files
           │             │
           │             └─ vim-clap Rustバイナリ
           │
           └─ [fzf使用時]
                  └─ spacevim#wrap#fzf#Files()
```

### データフロー図

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

キー入力 ──────▶ manager.vim ────────▶ Clap/fzf分岐
                       │                    │
                       │                    ▼
               [vim-clap有効時]        Clapコマンド
                       │                    │
                       │                    ▼
                       │           フローティングウィンドウ
                       │                    │
                       │                    ▼
                       │           Rustファジーマッチング
                       │                    │
                       └────────────────────┘
                                │
                                ▼
                         ファイルオープン
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+tools/fzf/packages.vim` | 設定 | vim-clapプラグインのロード |
| config.vim | `layers/+tools/fzf/config.vim` | 設定 | コマンド履歴等のClap分岐 |
| manager.vim | `core/autoload/spacevim/map/manager.vim` | ソース | vim-clap/fzf切り替えマネージャー |
