# 機能設計書 35-CtrlP連携

## 概要

本ドキュメントは、space-vimにおけるCtrlP連携機能の設計仕様を定義する。CtrlPはVimScriptで実装された軽量なファジーファインダーであり、ファイル検索、バッファ検索、MRU（Most Recently Used）検索などの機能を提供する。

### 本機能の処理概要

CtrlP連携機能は、Ctrl-Pキーで起動する伝統的なファジーファインダーをspace-vimに統合する。CtrlPは外部依存なしに動作する純粋なVimScriptプラグインであり、軽量性と互換性の高さが特徴である。agやgitコマンドとの連携により、高速なファイル検索も実現可能である。

**業務上の目的・背景**：fzfのインストールが困難な環境や、外部依存を最小化したいユーザーにとって、CtrlPは信頼性の高い選択肢である。VimScriptのみで実装されているため、あらゆるVim環境で動作する。また、Pythonマッチャー（ctrlp-py-matcher）との連携により、大規模プロジェクトでも高速な検索が可能となる。

**機能の利用シーン**：
- Ctrl-Pキーでのファイル検索（伝統的なCtrlPの使い方）
- MRUファイルの検索（:CtrlPMRU）
- 外部依存を最小化したい環境でのファジー検索
- agやgitと連携した高速ファイル検索

**主要な処理内容**：
1. ファイル検索（:CtrlP）- カレントディレクトリ以下のファイル一覧をファジー検索
2. MRU検索（:CtrlPMRU）- 最近使用したファイルをファジー検索
3. Pythonマッチャー連携 - ctrlp-py-matcherによる高速マッチング
4. ag連携 - The Silver Searcherによる高速ファイルリスト取得

**関連システム・外部連携**：
- ag（The Silver Searcher）- 高速ファイルリスト取得
- git - gitリポジトリ内ファイルの高速取得
- ctrlp-py-matcher - Pythonによる高速マッチング

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | CtrlP（ファイル検索） | 主画面 | Ctrl-Pで起動するファイル検索ウィンドウ |

## 機能種別

検索処理 / UI操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:ctrlp_working_path_mode | String | No | 作業ディレクトリモード（'ra'等） | 有効なモード文字 |
| g:ctrlp_match_window_bottom | Number | No | マッチウィンドウを下部に表示（0で上部） | 0 or 1 |
| g:ctrlp_by_filename | Number | No | ファイル名のみでマッチ（1で有効） | 0 or 1 |
| g:ctrlp_max_height | Number | No | マッチウィンドウの最大高さ | 正の整数 |
| g:ctrlp_use_caching | Number | No | キャッシュを使用（1で有効） | 0 or 1 |
| g:ctrlp_regexp | Number | No | 正規表現モード（1で有効） | 0 or 1 |
| g:ctrlp_mruf_max | Number | No | MRUの最大記録数 | 正の整数 |
| g:ctrlp_user_command | String/List | No | ファイルリスト取得コマンド | 有効なシェルコマンド |
| g:ctrlp_custom_ignore | Dict | No | 無視パターンの設定 | 有効な正規表現 |

### 入力データソース

- ファイルシステム（:CtrlP）
- Vim MRUリスト（:CtrlPMRU）
- agコマンド出力（ag使用時）
- gitコマンド出力（git使用時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 選択ファイルパス | String | ユーザーが選択したファイルのパス |

### 出力先

- エディタバッファ（ファイルを開く）
- 新規タブ（Ctrl-t）
- 水平分割（Ctrl-x）
- 垂直分割（Ctrl-v）

## 処理フロー

### 処理シーケンス

```
1. CtrlPコマンド実行
   └─ Ctrl-P または :CtrlP コマンド呼び出し
2. プロジェクトルート検出
   └─ g:ctrlp_working_path_modeに基づきルートを検出
3. ファイルリスト取得
   └─ ag/git/find等でファイル一覧を取得
4. CtrlPウィンドウ表示
   └─ 分割ウィンドウでCtrlPインターフェース表示
5. ユーザー入力によるフィルタリング
   └─ ctrlp-py-matcherまたは組み込みマッチャーでフィルタリング
6. 選択結果の処理
   └─ ファイルオープン
```

### フローチャート

```mermaid
flowchart TD
    A[Ctrl-P押下] --> B[プロジェクトルート検出]
    B --> C{ag利用可能?}
    C -->|Yes| D[agでファイルリスト取得]
    C -->|No| E{gitリポジトリ?}
    E -->|Yes| F[git ls-filesでファイルリスト取得]
    E -->|No| G[組み込みのファイルスキャン]
    D --> H[CtrlPウィンドウ表示]
    F --> H
    G --> H
    H --> I[ユーザー入力待ち]
    I --> J{py-matcher利用可能?}
    J -->|Yes| K[Pythonマッチング]
    J -->|No| L[組み込みマッチング]
    K --> M[候補リスト更新]
    L --> M
    M --> I
    I --> N{選択/キャンセル}
    N -->|選択| O[ファイルを開く]
    N -->|キャンセル| P[ウィンドウ閉じる]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 遅延読み込み | tmuxレイヤー未使用時は遅延読み込み | tmuxレイヤー無効時 |
| BR-02 | ag優先 | agが利用可能な場合、ファイルリスト取得にagを使用 | ag実行可能時 |
| BR-03 | キャッシュ無効化（ag使用時） | agが十分高速なためキャッシュを無効化 | ag使用時 |
| BR-04 | git fallback | ag未使用かつgitリポジトリ内の場合、git ls-filesを使用 | 条件該当時 |
| BR-05 | 正規表現モード | g:ctrlp_regexp=1で正規表現による検索 | 設定有効時 |

### 計算ロジック

該当なし

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| CTRLP-001 | Python未対応 | ctrlp-py-matcherでPythonが利用不可 | 組み込みマッチャーにフォールバック |
| CTRLP-002 | 大規模プロジェクト | ファイル数が多くスキャンに時間がかかる | agまたはgitの使用を推奨 |

### リトライ仕様

特になし。処理は同期的に実行される。

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

該当なし

## パフォーマンス要件

- ファイル一覧表示: 2秒以内（キャッシュ利用時は即座）
- インクリメンタル検索: 200ms以内のレスポンス
- ag使用時: 1秒以内でファイルリスト取得

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

- g:ctrlp_user_commandの外部コマンド実行に注意
- シンボリックリンクの追跡設定（g:ctrlp_follow_symlinks）

## 備考

- fzfが利用可能な環境ではfzfを優先使用することを推奨
- Pythonマッチャーのインストールで大幅な高速化が可能
- MRUは終了時にも保持される

---

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

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

### 推奨読解順序

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

CtrlPの設定変数の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.vim | `layers/+vim/ctrlp/config.vim` | g:ctrlp_*変数の設定 |

**読解のコツ**: CtrlPの設定は全て`g:ctrlp_`プレフィックスで始まる。特に`g:ctrlp_user_command`がファイルリスト取得方法を決定する重要な設定。

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

CtrlPのプラグインロードと遅延読み込みを理解する。

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

**主要処理フロー**:
1. **1-3行目**: tmuxレイヤー使用時は即座にロード
2. **4-6行目**: tmuxレイヤー未使用時は遅延読み込み（on: ['CtrlP', 'CtrlPMRU']）
3. **7行目**: ctrlp-py-matcherも同様の条件でロード

#### Step 3: 設定詳細を理解する

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

**主要処理フロー**:
- **2行目**: `g:ctrlp_working_path_mode = 'ra'` - .git等の祖先ディレクトリとカレントディレクトリを検索
- **3行目**: `g:ctrlp_match_window_bottom = 0` - マッチウィンドウを上部に表示
- **4行目**: `g:ctrlp_by_filename = 1` - ファイル名のみでマッチ
- **11行目**: `g:ctrlp_map = '<c-p>'` - Ctrl-Pキーマッピング
- **16-20行目**: `g:ctrlp_custom_ignore` - 無視パターン（.git, .hg, .svn等）
- **23-29行目**: ag利用時の設定
- **31行目**: git fallback設定
- **34行目**: `g:ctrlp_match_func` - Pythonマッチャーの設定
- **35-36行目**: キーマッピング（Leader fr, C-p）

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

```
<C-p> (キーバインド)
    │
    └─ :CtrlP
           │
           ├─ g:ctrlp_user_command
           │      │
           │      ├─ [ag利用可能]
           │      │      └─ ag %s -l --nocolor -g ""
           │      │
           │      └─ [git利用可能]
           │             └─ git ls-files -oc --exclude-standard
           │
           └─ g:ctrlp_match_func
                  │
                  └─ pymatcher#PyMatch()
```

### データフロー図

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

Ctrl-P ──────▶ CtrlP起動 ─────────▶ ファイルリスト取得
                    │                     │
                    │                     ▼
                    │              [ag/git/find]
                    │                     │
                    │                     ▼
                    │              CtrlPウィンドウ
                    │                     │
                    │                     ▼
                    │              マッチング処理
                    │                     │
                    └─────────────────────┘
                                │
                                ▼
                         ファイルオープン
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+vim/ctrlp/packages.vim` | 設定 | CtrlPプラグインのロード |
| config.vim | `layers/+vim/ctrlp/config.vim` | 設定 | CtrlPオプション・キーバインド設定 |
