# 機能設計書 16-プロジェクト検索(SPC p)

## 概要

本ドキュメントは、space-vimにおけるプロジェクト検索機能（SPC p）の設計仕様を記述する。SPCキーに続いて「p」を押下することで、プロジェクト内のファイル検索、テキスト検索（grep/ripgrep）などのプロジェクト関連操作を提供する機能である。

### 本機能の処理概要

プロジェクト検索機能は、カレントプロジェクト内でのファイル検索とテキスト検索を統合的に提供する。fzf/vim-clapと連携し、ripgrep（rg）やsilver searcher（ag）を使用した高速な全文検索を実現する。

**業務上の目的・背景**：大規模なソフトウェアプロジェクトでは、数千から数万のファイルが存在することがある。プロジェクト検索機能により、プロジェクト全体からファイル名やテキスト内容で素早く目的の箇所を見つけることができる。標準のVimの:grep/vimgrepは遅いが、ripgrepと連携することで実用的な速度を実現。

**機能の利用シーン**：
- プロジェクト内の特定ファイルを名前で検索する場合（SPC p f）
- プロジェクト内のコードを全文検索する場合（SPC p s / SPC p r）
- カーソル下の単語でプロジェクト内を検索する場合（SPC p w / SPC p W）
- agを使用した全文検索を行う場合（SPC p a）

**主要な処理内容**：
1. SPC p f：プロジェクト内ファイル検索（FindFiles）
2. SPC p s / SPC p r：ripgrepによるプロジェクト内テキスト検索
3. SPC p a：silver searcher（ag）によるテキスト検索
4. SPC p w：カーソル下の単語でripgrep検索
5. SPC p W：カーソル下の単語でfzf検索

**関連システム・外部連携**：
- fzf.vim / vim-clap：ファジーファインダーUI
- ripgrep（rg）：高速テキスト検索ツール
- silver searcher（ag）：テキスト検索ツール

**権限による制御**：本機能に権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | FZF（ファジーファインダー） | 補助機能 | プロジェクト内のファイル検索、テキスト検索（rg連携） |

## 機能種別

検索 / ナビゲーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| キーシーケンス | String | Yes | SPC p に続くキー入力 | 定義済みキーのみ受付 |
| 検索パターン | String | No | 検索文字列（対話入力またはカーソル下単語） | - |

### 入力データソース

- ユーザーキー入力
- カーソル下の単語（SPC p w / SPC p W使用時）
- プロジェクトファイルシステム

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 検索結果一覧 | fzf UI | マッチしたファイル/行の一覧 |
| ジャンプ先 | Vim位置 | 選択された検索結果の位置 |

### 出力先

- fzfフローティングウィンドウ
- Vimバッファ（選択後のジャンプ先）

## 処理フロー

### 処理シーケンス

```
1. SPC p キー入力
   └─ which-keyによるサブキー一覧表示
2. サブキー入力に応じた処理分岐
   ├─ f:    プロジェクト内ファイル検索（spacevim#map#manager#FindFiles()）
   ├─ s/r:  ripgrepによるテキスト検索（spacevim#map#manager#Rg()）
   ├─ a:    silver searcherによるテキスト検索（:Rag）
   ├─ w:    カーソル下単語でripgrep検索（spacevim#map#manager#RgCword()）
   └─ W:    カーソル下単語でfzf検索（spacevim#plug#fzf#SearchCword()）
3. fzf/vim-clapによる検索UI表示
4. ユーザー選択
5. 選択結果へジャンプ
```

### フローチャート

```mermaid
flowchart TD
    A[SPC p 入力] --> B{サブキー?}
    B -->|f| C[プロジェクトファイル検索]
    B -->|s/r| D[ripgrepテキスト検索]
    B -->|a| E[agテキスト検索]
    B -->|w| F[カーソル下単語でrg検索]
    B -->|W| G[カーソル下単語でfzf検索]
    C --> H{vim-clap有効?}
    D --> H
    E --> I[Rag実行]
    F --> H
    G --> J[fzf SearchCword実行]
    H -->|Yes| K[Clap files/grep2実行]
    H -->|No| L[fzf Files/Rg実行]
    I --> M[fzf結果表示]
    J --> M
    K --> M
    L --> M
    M --> N{選択?}
    N -->|Yes| O[選択位置へジャンプ]
    N -->|No| P[キャンセル]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | vim-clap優先 | g:spacevim_enable_clap=1でvim-clap使用 | g:spacevim_enable_clap設定時 |
| BR-002 | fzfフォールバック | vim-clap未設定時はfzf.vim使用 | g:spacevim_enable_clap未設定時 |
| BR-003 | ripgrep必須 | SPC p s/r/wはripgrepが必要 | rgコマンドがインストール済み |
| BR-004 | プロジェクトルート検出 | Gitルートまたはカレントディレクトリを使用 | 検索実行時 |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コマンド未検出 | rg/agがインストールされていない | 必要なツールをインストール |
| - | 検索結果なし | マッチする結果がない | メッセージ表示 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- ファイル検索は初回インデックス構築後は即時表示
- ripgrepによるテキスト検索は大規模プロジェクトでも実用的な速度（数秒以内）

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

- .gitignoreで除外されたファイルは検索対象外（ripgrepのデフォルト動作）

## 備考

- ripgrep（rg）のインストールが推奨される
- vim-clapを使用するとよりモダンなUIを利用可能

---

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

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

### 推奨読解順序

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

プロジェクト検索のキーマッピング定義を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | leader.vim | `core/autoload/spacevim/map/leader.vim` | s:leader_map['p']の構造を理解 |

**読解のコツ**: プロジェクト検索は関数呼び出しが多く、実装はmanager.vimに委譲されている。

**主要データ構造**:
- **140行目**: `let s:leader_map['p'] = {` - プロジェクト操作グループ開始
- **141行目**: `'name' : '+projects'` - グループ名
- **142行目**: `'f' : ['spacevim#map#manager#FindFiles()', 'find-file-in-project']` - ファイル検索
- **143行目**: `'s' : ['spacevim#map#manager#Rg()', 'search-in-project']` - テキスト検索
- **144行目**: `'a' : ['Rag', 'search-in-project-via-ag']` - ag検索
- **145行目**: `'r' : ['spacevim#map#manager#Rg()', 'search-in-project-via-rg']` - rg検索
- **146行目**: `'w' : ['spacevim#map#manager#RgCword()', 'find-cword-in-project-via-rg']` - カーソル下単語rg検索
- **147行目**: `'W' : ['spacevim#plug#fzf#SearchCword()', 'find-cword-in-project']` - カーソル下単語fzf検索

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | manager.vim | `core/autoload/spacevim/map/manager.vim` | FindFiles, Rg, RgCword関数の実装 |

**主要処理フロー**:
- **142-148行目**: `spacevim#map#manager#FindFiles()` - ファイル検索
  - vim-clap有効: `Clap files`
  - それ以外: `spacevim#plug#fzf#FindFileInProject()`
- **78-85行目**: `spacevim#map#manager#Rg()` - ripgrep検索
  - vim-clap有効: `Clap grep2`
  - それ以外: `:Rg`
- **69-76行目**: `spacevim#map#manager#RgCword()` - カーソル下単語検索
  - vim-clap有効: `Clap grep2 ++query=<cword>`
  - それ以外: `spacevim#plug#fzf#RgCursorWord()`

#### Step 3: fzfプラグイン実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | fzf.vim | `core/autoload/spacevim/plug/fzf.vim` | fzf関連関数の実装 |
| 3-2 | config.vim | `layers/+tools/fzf/config.vim` | Rg/Ragコマンド定義 |

**主要処理フロー**:
- **56-58行目（config.vim）**: `:Rag`コマンド定義 - agによる検索
- **58行目（config.vim）**: `:Rg`コマンド定義 - rgによる検索

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

```
SPC p キー入力
    │
    ├─ SPC p f
    │      └─ spacevim#map#manager#FindFiles()
    │             ├─ g:spacevim_enable_clap=1
    │             │      └─ :Clap files
    │             └─ それ以外
    │                    └─ spacevim#plug#fzf#FindFileInProject()
    │
    ├─ SPC p s / SPC p r
    │      └─ spacevim#map#manager#Rg()
    │             ├─ g:spacevim_enable_clap=1
    │             │      └─ :Clap grep2
    │             └─ それ以外
    │                    └─ :Rg (fzf.vim)
    │
    ├─ SPC p a
    │      └─ :Rag (ag検索)
    │             └─ spacevim#plug#fzf#AgInProject()
    │
    ├─ SPC p w
    │      └─ spacevim#map#manager#RgCword()
    │             ├─ g:spacevim_enable_clap=1
    │             │      └─ :Clap grep2 ++query=<cword>
    │             └─ それ以外
    │                    └─ spacevim#plug#fzf#RgCursorWord()
    │
    └─ SPC p W
           └─ spacevim#plug#fzf#SearchCword()
```

### データフロー図

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

ユーザーキー入力 ────▶ which-keyディスパッチ ───▶ サブキー選択UI
    │                       │
    ▼                       ▼
SPC p + サブキー ────▶ manager関数呼び出し ─────▶ vim-clap/fzf選択
                            │
                            ├─▶ Clap files ─────▶ ファイル選択UI
                            ├─▶ Clap grep2 ─────▶ テキスト検索UI
                            ├─▶ :Rg ────────────▶ fzf検索UI
                            └─▶ :Rag ───────────▶ ag検索UI
                                    │
                                    ▼
                            選択結果 ────────────▶ ファイルジャンプ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| leader.vim | `core/autoload/spacevim/map/leader.vim` | ソース | プロジェクト検索キーマッピング定義 |
| manager.vim | `core/autoload/spacevim/map/manager.vim` | ソース | FindFiles, Rg, RgCword関数実装 |
| fzf.vim | `core/autoload/spacevim/plug/fzf.vim` | ソース | fzf関連関数実装 |
| config.vim | `layers/+tools/fzf/config.vim` | 設定 | Rg/Ragコマンド定義 |
| fzf_base.vim | `core/autoload/spacevim/plug/fzf_base.vim` | ソース | fzf基本機能 |
