# 機能設計書 32-fzf連携

## 概要

本ドキュメントは、space-vimにおけるfzf連携機能の設計仕様を定義する。fzfは高速なファジーファインダーであり、ファイル検索、バッファ検索、コマンド履歴検索など、多様な検索機能を提供する。space-vimのデフォルトファジーファインダーとして統合されている。

### 本機能の処理概要

fzf連携機能は、VimエディタにGoで実装された高速ファジーファインダー「fzf」を統合し、あいまい検索（ファジーマッチング）による効率的なファイル・バッファ・コマンド検索を実現する。fzf.vimプラグインと連携し、プレビュー機能やripgrep(rg)との統合による強力なプロジェクト内検索を提供する。

**業務上の目的・背景**：大規模プロジェクトでのファイル検索は、ディレクトリ構造を把握していなくても目的のファイルに素早くアクセスできる必要がある。fzfはインクリメンタルなあいまい検索により、ファイル名の一部を入力するだけで候補を絞り込み、開発効率を大幅に向上させる。

**機能の利用シーン**：
- プロジェクト内のファイルを名前で検索する場合
- 開いているバッファ間を素早く切り替える場合
- 以前実行したコマンドを再実行する場合
- プロジェクト内のテキストをgrep検索する場合
- 最近開いたファイルを検索する場合

**主要な処理内容**：
1. ファイル検索（:Files）- カレントディレクトリ以下のファイル一覧をファジー検索
2. バッファ検索（:Buffers）- 開いているバッファをファジー検索
3. テキスト検索（:Rg, :Ag）- ripgrepまたはagによるプロジェクト内全文検索
4. コマンド履歴検索（:History:）- 過去に実行したExコマンドを検索
5. 行検索（:BLines）- 現在のバッファ内の行をファジー検索

**関連システム・外部連携**：
- fzf（Go製ファジーファインダー）
- fzf.vim（Vim統合プラグイン）
- ripgrep（rg）- 高速grep代替
- ag（The Silver Searcher）- 高速grep代替
- bat - プレビュー用シンタックスハイライト

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | FZF（ファジーファインダー） | 主画面 | ファジー検索によるファイル・バッファ・コマンド履歴の検索 |
| 17 | Quickfix/Location List | 遷移先画面 | 検索結果からQuickfixリストへの遷移 |

## 機能種別

検索処理 / UI操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:fzf_layout | Dict | No | FZFウィンドウのレイアウト設定 | 有効なレイアウトキー |
| g:fzf_colors | Dict | No | FZFのカラースキーム設定 | 有効なハイライトグループ |
| g:spacevim_enable_clap | Number | No | vim-clap使用フラグ（1で有効） | 0 or 1 |
| $FZF_DEFAULT_OPTS | String | No | FZFのデフォルトオプション | 有効なFZFオプション |

### 入力データソース

- ファイルシステム（:Files）
- Vimバッファリスト（:Buffers）
- Vimコマンド履歴（:History:）
- ripgrep/ag出力（:Rg, :Ag）
- カレントバッファ内容（:BLines）

## 出力仕様

### 出力データ

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

### 出力先

- エディタバッファ（ファイルを開く）
- コマンドライン（コマンド実行）
- Quickfixリスト（複数選択時）

## 処理フロー

### 処理シーケンス

```
1. FZFコマンド実行
   └─ :Files, :Buffers, :Rg 等のコマンド呼び出し
2. データソースの取得
   └─ ファイル一覧、バッファ一覧、grep結果等を収集
3. FZFウィンドウ表示
   └─ フローティングウィンドウまたは分割ウィンドウで表示
4. ユーザー入力によるフィルタリング
   └─ インクリメンタルにファジーマッチング実行
5. 選択結果の処理
   └─ ファイルオープン、コマンド実行等
```

### フローチャート

```mermaid
flowchart TD
    A[FZFコマンド実行] --> B{コマンド種別}
    B -->|Files| C[ファイル一覧取得]
    B -->|Buffers| D[バッファ一覧取得]
    B -->|Rg| E[ripgrep実行]
    B -->|BLines| F[現在バッファの行取得]
    C --> G[FZFウィンドウ表示]
    D --> G
    E --> G
    F --> G
    G --> H[ユーザー入力待ち]
    H --> I{ファジーマッチング}
    I --> J[候補リスト更新]
    J --> H
    H --> K{選択/キャンセル}
    K -->|選択| L[アクション実行]
    K -->|キャンセル| M[ウィンドウ閉じる]
    L --> N{アクション種別}
    N -->|Enter| O[ファイルを開く]
    N -->|Ctrl-t| P[新規タブで開く]
    N -->|Ctrl-x| Q[水平分割で開く]
    N -->|Ctrl-v| R[垂直分割で開く]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | vim-clap優先 | g:spacevim_enable_clap=1の場合、fzfの代わりにvim-clapを使用 | 設定有効時 |
| BR-02 | LeaderF優先（GUI） | GUIかつターミナル未対応の場合、LeaderFを使用 | GUI環境 |
| BR-03 | 遅延読み込み | speed_up_via_timer有効時、700ms後にfzfをロード | 設定有効時 |
| BR-04 | フローティングウィンドウ | NeoVim使用時、nvim_open_winでフローティング表示 | NeoVim環境 |

### 計算ロジック

該当なし

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FZF-001 | fzf未インストール | fzfバイナリが見つからない | ~/.fzfへの自動インストール |
| FZF-002 | rg未インストール | :Rg実行時にrgが見つからない | 警告メッセージ表示 |
| FZF-003 | プロジェクトルート未検出 | Ragコマンドでルート判定失敗 | カレントディレクトリを使用 |

### リトライ仕様

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

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

該当なし

## パフォーマンス要件

- ファイル一覧表示: 1秒以内（数万ファイルプロジェクトでも）
- インクリメンタル検索: 100ms以内のレスポンス
- プレビュー表示: 200ms以内

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

- 外部コマンド（fzf, rg, ag）の実行パスを確認
- シェルエスケープの適切な処理（shellescape関数使用）

## 備考

- fzfは初回起動時に~/.fzfにインストールされる
- プレビュー機能にはbatのインストールを推奨
- vim-clapが有効な場合、fzfは読み込まれない

---

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

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

### 推奨読解順序

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

FZFの設定構造とレイアウト定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.vim | `layers/+tools/fzf/config.vim` | g:fzf_layout, g:fzf_colorsの構造 |
| 1-2 | fzf_base.vim | `core/autoload/spacevim/plug/fzf_base.vim` | s:default_actionの定義 |

**読解のコツ**: g:fzf_layoutは'down', 'up', 'left', 'right', 'window'キーでウィンドウ位置を指定。NeoVimではフローティングウィンドウも利用可能。

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

FZFレイヤーのロードと初期化処理を理解する。

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

**主要処理フロー**:
1. **1-3行目**: vim-clap有効時の分岐
2. **4-5行目**: GUI環境でのLeaderF使用
3. **6-14行目**: fzf/fzf.vimのロード（遅延読み込み対応）

#### Step 3: キーバインド設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.vim | `layers/+tools/fzf/config.vim` | キーマッピングの定義 |

**主要処理フロー**:
- **1-4行目**: 基本キーマッピング（Leader ff, bb, fl, fL）
- **50-51行目**: Ag/Filesコマンドのカスタム定義（プレビュー付き）
- **56-58行目**: Rag/Rgコマンドの定義

#### Step 4: FZFラッパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | fzf.vim | `core/autoload/spacevim/plug/fzf.vim` | 各種検索関数の実装 |

**主要処理フロー**:
- **8-15行目**: Session関数（セッション検索）
- **20-31行目**: Open関数（クイックオープン）
- **158-160行目**: FindFileInProject関数
- **195-223行目**: Rg関数（ripgrep検索）

#### Step 5: マネージャー関数を理解する

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

**主要処理フロー**:
- **11-17行目**: Buffers関数（vim-clap/fzf分岐）
- **19-25行目**: Files関数
- **78-85行目**: Rg関数

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

```
<Leader>ff (キーバインド)
    │
    └─ spacevim#map#manager#Files()
           │
           ├─ [vim-clap有効時]
           │      └─ :Clap files
           │
           └─ [fzf使用時]
                  └─ spacevim#plug#fzf#FindFileInProject()
                         │
                         └─ :FZF {RootDirectory}
                                │
                                └─ fzf#run()
```

### データフロー図

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

キー入力 ──────▶ manager.vim ────────▶ fzf.vim
                       │                    │
                       │                    ▼
                       │              FZFウィンドウ
                       │                    │
                       │                    ▼
                       │              ユーザー選択
                       │                    │
                       └────────────────────┘
                                │
                                ▼
                         ファイルオープン
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+tools/fzf/packages.vim` | 設定 | fzf/fzf.vimプラグインのロード |
| config.vim | `layers/+tools/fzf/config.vim` | 設定 | キーバインド・オプション設定 |
| fzf.vim | `core/autoload/spacevim/plug/fzf.vim` | ソース | FZF検索関数の実装 |
| fzf_base.vim | `core/autoload/spacevim/plug/fzf_base.vim` | ソース | FZF基盤関数（バッファ検索等） |
| manager.vim | `core/autoload/spacevim/map/manager.vim` | ソース | vim-clap/fzf切り替えマネージャー |
| fzf.vim | `core/ftplugin/fzf.vim` | 設定 | FZFバッファのファイルタイプ設定 |
| wrap/fzf.vim | `core/autoload/spacevim/wrap/fzf.vim` | ソース | FZFラッパー関数 |
