# 機能設計書 33-LeaderF連携

## 概要

本ドキュメントは、space-vimにおけるLeaderF連携機能の設計仕様を定義する。LeaderFはPythonで実装された高速なファジーファインダーであり、GUI環境でターミナル機能が利用できない場合のfzf代替として使用される。

### 本機能の処理概要

LeaderF連携機能は、VimのGUI環境（gVim等）においてファジー検索機能を提供する。fzfはターミナル機能を必要とするため、ターミナルをサポートしないGUI Vimでは動作しない。LeaderFはPure Vimscript + Pythonで実装されており、GUI環境でも高速なファジー検索を実現する。

**業務上の目的・背景**：GUI版Vim（gVim、MacVim等）を使用するユーザーにとって、fzfが利用できない環境でもファジー検索機能は必須である。LeaderFはPythonの高速なマッチングアルゴリズムにより、ターミナル非対応環境でも効率的なファイル検索を提供する。

**機能の利用シーン**：
- gVim、MacVimなどのGUI版Vimでのファイル検索
- ターミナル機能が無効化されたVim環境での検索
- MRU（Most Recently Used）ファイルの検索
- バッファ内タグの検索

**主要な処理内容**：
1. ファイル検索（:LeaderfFile）- カレントディレクトリ以下のファイル一覧をファジー検索
2. MRU検索（:LeaderfMru）- 最近使用したファイルをファジー検索
3. バッファタグ検索（:LeaderfBufTag）- 現在のバッファ内のタグを検索
4. 関数検索 - 現在のバッファ内の関数定義を検索

**関連システム・外部連携**：
- Python（LeaderFの高速マッチング機能に必要）
- fzfレイヤーのフォールバックとして機能

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

## 関連画面

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

## 機能種別

検索処理 / UI操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:Lf_ReverseOrder | Number | No | 検索結果を逆順表示（1で有効） | 0 or 1 |
| g:Lf_WindowPosition | String | No | ウィンドウ位置（'popup', 'bottom', 'top'等） | 有効な位置指定 |
| g:Lf_PreviewInPopup | Number | No | ポップアップでプレビュー表示（1で有効） | 0 or 1 |

### 入力データソース

- ファイルシステム（:LeaderfFile）
- Vim MRUリスト（:LeaderfMru）
- ctagsタグ情報（:LeaderfBufTag）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 選択ファイルパス | String | ユーザーが選択したファイルのパス |
| 選択タグ | String | 選択されたタグ名と位置情報 |

### 出力先

- エディタバッファ（ファイルを開く）
- カーソル位置（タグジャンプ）

## 処理フロー

### 処理シーケンス

```
1. LeaderFコマンド実行
   └─ :LeaderfFile, :LeaderfMru 等のコマンド呼び出し
2. データソースの取得
   └─ Pythonによるファイル一覧取得・キャッシュ利用
3. LeaderFウィンドウ表示
   └─ ポップアップまたは分割ウィンドウで表示
4. ユーザー入力によるフィルタリング
   └─ Pythonによる高速ファジーマッチング
5. 選択結果の処理
   └─ ファイルオープン、タグジャンプ等
```

### フローチャート

```mermaid
flowchart TD
    A[LeaderFコマンド実行] --> B{コマンド種別}
    B -->|LeaderfFile| C[ファイル一覧取得]
    B -->|LeaderfMru| D[MRUリスト取得]
    B -->|LeaderfBufTag| E[バッファタグ取得]
    C --> F[LeaderFウィンドウ表示]
    D --> F
    E --> F
    F --> G[ユーザー入力待ち]
    G --> H[Pythonファジーマッチング]
    H --> I[候補リスト更新]
    I --> G
    G --> J{選択/キャンセル}
    J -->|選択| K[ファイルを開く/タグジャンプ]
    J -->|キャンセル| L[ウィンドウ閉じる]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | GUI環境限定 | GUI環境かつターミナル未対応時のみLeaderFを使用 | `g:spacevim.gui && !has('terminal')` |
| BR-02 | 逆順表示 | g:Lf_ReverseOrder=1で検索結果を逆順表示 | 設定有効時 |
| BR-03 | Pythonキャッシュ | ファイル一覧をPythonでキャッシュして高速化 | 常時 |

### 計算ロジック

該当なし

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| LF-001 | Python未対応 | Python2/3が利用不可 | Pythonのインストールを案内 |
| LF-002 | タグファイル未生成 | BufTagでタグが見つからない | ctagsの実行を案内 |

### リトライ仕様

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

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

該当なし

## パフォーマンス要件

- ファイル一覧表示: 1秒以内
- インクリメンタル検索: 100ms以内のレスポンス
- キャッシュ利用時: 即座に表示

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

- Pythonスクリプトの実行権限を確認
- 外部Pythonモジュールへの依存なし

## 備考

- Python 2.7+ または Python 3.x が必要
- fzfが利用可能な環境ではfzfを優先使用
- vim-clapが有効な場合、LeaderFは読み込まれない

---

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

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

### 推奨読解順序

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

LeaderFの起動条件を理解する。

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

**読解のコツ**: `g:spacevim.gui && !has('terminal')` の条件式がLeaderF使用の判定。GUI環境でかつターミナル機能がない場合にLeaderFが選択される。

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

LeaderFのプラグインロードと基本設定を理解する。

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

**主要処理フロー**:
1. **4-5行目**: GUI環境判定とLeaderFプラグインロード
   - `elseif g:spacevim.gui && !has('terminal')`
   - `MP 'Yggdroot/LeaderF'`

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

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

**主要処理フロー**:
- **14-18行目**: LeaderF用キーマッピング
  - `g:Lf_ReverseOrder = 1` - 逆順表示設定
  - `Leader f?` - LeaderfFile呼び出し
  - `Leader fr` - LeaderfMru呼び出し

#### Step 4: マネージャー関数での分岐を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | manager.vim | `core/autoload/spacevim/map/manager.vim` | LeaderF分岐ロジック |

**主要処理フロー**:
- **39-41行目**: BufTags関数でのLeaderF分岐
  - `elseif exists(':LeaderfBufTag')`
  - `LeaderfBufTag`

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

```
<Leader>f? (キーバインド)
    │
    └─ :LeaderfFile
           │
           └─ LeaderFプラグイン
                  │
                  ├─ Pythonファジーマッチング
                  │
                  └─ ファイルオープン
```

### データフロー図

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

キー入力 ──────▶ config.vim ─────────▶ LeaderFコマンド
                       │                    │
                       │                    ▼
                       │              LeaderFウィンドウ
                       │                    │
                       │                    ▼
                       │              Pythonマッチング
                       │                    │
                       └────────────────────┘
                                │
                                ▼
                         ファイルオープン
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+tools/fzf/packages.vim` | 設定 | LeaderFプラグインのロード条件 |
| config.vim | `layers/+tools/fzf/config.vim` | 設定 | キーバインド・オプション設定 |
| manager.vim | `core/autoload/spacevim/map/manager.vim` | ソース | LeaderF/fzf切り替えマネージャー |
