# 機能設計書 22-Ivyファジー検索・補完フレームワーク

## 概要

本ドキュメントは、Doom EmacsにおけるIvyファジー検索・補完フレームワーク機能の設計を記述する。Ivyは軽量かつ高速なミニバッファ補完フレームワークであり、Counselパッケージと組み合わせることで強力な検索・ナビゲーション機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：開発者がファイル、バッファ、コマンド、シンボルなどを効率的に検索・選択できる環境を提供する。Ivyは軽量設計により高速な応答性を実現し、大規模プロジェクトでもストレスなく操作できる。Counselとの連携により、Emacsの標準コマンドを拡張した高機能な検索インターフェースを提供する。

**機能の利用シーン**：ファイルを開く際（`counsel-find-file`）、バッファを切り替える際（`+ivy/switch-buffer`）、コマンドを実行する際（`counsel-M-x`）、プロジェクト内のファイルを検索する際（`counsel-projectile-find-file`）、テキストを検索する際（`counsel-rg`によるripgrep検索）、変数や関数の説明を参照する際（`counsel-describe-*`）など。

**主要な処理内容**：
1. ミニバッファでのインクリメンタル補完インターフェースの表示
2. 正規表現またはファジーマッチングによる候補絞り込み
3. better-jumperとの統合によるジャンプポイント管理
4. Projectile連携によるプロジェクト単位のファイル・バッファ管理
5. ripgrep連携によるプロジェクト横断テキスト検索
6. wgrepによる検索結果の一括編集機能
7. ivy-posframe（+childframeフラグ有効時）によるポップアップ表示
8. prescient.el（+prescientフラグ有効時）による履歴ベースソート

**関連システム・外部連携**：Counselとの連携による拡張コマンド、Projectileとの連携によるプロジェクト管理、ripgrepとの連携によるテキスト検索、wgrepとの連携による編集機能、better-jumperとの連携によるジャンプ管理。

**権限による制御**：本機能は全ユーザーが利用可能であり、権限による制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | Ivy | 主機能 | ミニバッファでのファジー補完、候補選択 |

## 機能種別

検索・選択UI / ナビゲーション / 補完フレームワーク

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| 検索クエリ | string | No | インクリメンタル検索のための入力文字列 | 任意の文字列を受け付ける |
| ivy-height | integer | No | 表示する候補数（デフォルト: 17） | 正の整数 |
| ivy-sort-max-size | integer | No | ソート対象の最大候補数（デフォルト: 7500） | 正の整数 |

### 入力データソース

- ユーザーのキーボード入力（ミニバッファ）
- ファイルシステム（ファイル検索時）
- バッファリスト（バッファ切り替え時）
- Projectileのプロジェクト情報
- ripgrepの検索結果

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 候補リスト | list | 検索条件に一致する候補のリスト |
| 選択結果 | varies | ユーザーが選択した項目 |

### 出力先

- ミニバッファまたはposframe（候補表示）
- 選択されたアクションに応じた出力先

## 処理フロー

### 処理シーケンス

```
1. ユーザーがIvy/Counselコマンドを呼び出し
   └─ キーバインドまたはM-xからコマンド実行
2. ivy-readによるセッション初期化
   └─ +ivy--originマーカーの設定（ジャンプポイント記録）
3. 候補の生成と表示
   └─ ivy-re-buildersによる正規表現構築
4. インクリメンタル検索ループ
   └─ ユーザー入力に応じた候補絞り込み
5. 候補の選択またはアクション選択
   └─ RETで選択、C-oでディスパッチ
6. アクションの実行
   └─ better-jumperへのジャンプポイント登録
7. セッションの終了
   └─ マーカーのクリーンアップ
```

### フローチャート

```mermaid
flowchart TD
    A[Ivy/Counselコマンド呼び出し] --> B[ivy-read初期化]
    B --> C[+ivy--origin設定]
    C --> D[候補生成・表示]
    D --> E{ユーザー入力}
    E -->|文字入力| F[候補絞り込み]
    F --> E
    E -->|RET| G[選択確定]
    E -->|C-o| H[アクション選択]
    E -->|C-g| I[キャンセル]
    H --> G
    G --> J[better-jumper登録]
    J --> K[アクション実行]
    K --> L[セッション終了]
    I --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-22-01 | ソート上限 | ivy-sort-max-size（7500）を超える候補はソートしない | 候補数が上限を超える場合 |
| BR-22-02 | ファジーマッチ | +fuzzyフラグ有効時、ivy--regex-fuzzyを使用 | +fuzzyモジュールフラグ有効時 |
| BR-22-03 | prescientソート | +prescientフラグ有効時、履歴ベースのソートを適用 | +prescientモジュールフラグ有効時 |
| BR-22-04 | 大規模プロジェクト対応 | ivy-sort-max-sizeを超えるプロジェクトではprojectile-find-fileにフォールバック | 大規模プロジェクト |

### 計算ロジック

特になし

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ERR-22-01 | ripgrep未検出 | ripgrep実行ファイルが見つからない | ユーザーにripgrepのインストールを促す |
| ERR-22-02 | wgrep未対応 | wgrep未対応のコマンドでwoccur実行 | user-errorで通知 |

### リトライ仕様

リトライ処理は実装されていない

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

該当なし

## パフォーマンス要件

- `ivy-sort-max-size`を7500に設定し、大量候補でのソートによるパフォーマンス低下を防止
- 候補数が上限を超える場合はソートをスキップ
- `ivy-rich`のリモートバッファ解析を無効化（`ivy-rich-parse-remote-buffer nil`）

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

- 外部コマンド（ripgrep、fd）の実行時は適切なエスケープ処理を実施
- `counsel-rg-base-command`はリスト形式で管理し、シェルインジェクションを防止

## 備考

- Ivy、Helm、Verticoは相互排他的な補完フレームワーク
- Counselパッケージが標準コマンドの置き換えを提供
- wgrepによる検索結果の一括編集が可能

---

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

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

### 推奨読解順序

#### Step 1: 設定と初期化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/completion/ivy/config.el` | メイン設定ファイル、変数定義、use-package設定 |
| 1-2 | packages.el | `modules/completion/ivy/packages.el` | 依存パッケージの定義 |

**読解のコツ**: `ivy-re-builders-alist`でマッチング方式を、`define-key!`でキーバインドを確認する。

**主要処理フロー**:
- **3-15行目**: カスタム変数定義（`+ivy-buffer-preview`等）
- **21-103行目**: ivy本体の設定（高さ、折り返し、プロンプト選択可能化）
- **43-47行目**: 標準コマンドのリマップ定義
- **82-95行目**: better-jumperとの統合設定
- **156-300行目**: counsel設定（rg、find-file、M-x等）

#### Step 2: 自動ロード関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ivy.el | `modules/completion/ivy/autoload/ivy.el` | カスタム関数群、バッファ切り替え、ファイル検索 |

**主要処理フロー**:
- **17-35行目**: `+ivy-rich-buffer-name` - バッファ名表示のカスタマイズ
- **95-127行目**: `+ivy--switch-buffer` - ワークスペース対応バッファ切り替え
- **212-237行目**: `+ivy/projectile-find-file` - インテリジェントファイル検索
- **240-282行目**: `+ivy-file-search` - ripgrep連携検索の中核

#### Step 3: 拡張機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/completion/ivy/config.el` | ivy-rich、counsel-projectile、wgrep、ivy-posframe設定 |

**主要処理フロー**:
- **106-147行目**: ivy-rich設定（表示変換、アイコン）
- **303-333行目**: counsel-projectile設定
- **341-362行目**: ivy-posframe設定（childframe）
- **377-402行目**: ivy-prescient設定（履歴ベースソート）

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

```
counsel-M-x / counsel-find-file / +ivy/switch-buffer
    │
    ├─ ivy-read (セッション管理)
    │      ├─ ivy-re-builders-alist (正規表現構築)
    │      └─ ivy-hooks-alist (+ivy--origin設定)
    │
    ├─ +ivy/projectile-find-file
    │      ├─ doom-project-root
    │      ├─ projectile-current-project-files
    │      └─ counsel-projectile-find-file / counsel-find-file
    │
    └─ +ivy-file-search
           ├─ counsel-rg
           └─ doom-thing-at-point-or-region
```

### データフロー図

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

ユーザー入力 ───▶ ivy-read ───▶ ivy-re-builder ───▶ 候補フィルタリング
                      │
                      └─▶ better-jumper ───▶ ジャンプポイント記録

ファイルシステム ───▶ counsel-find-file ───▶ ファイルオープン

ripgrep結果 ───────▶ counsel-rg ───▶ wgrep ───▶ 一括編集
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/completion/ivy/config.el` | ソース | メイン設定ファイル |
| packages.el | `modules/completion/ivy/packages.el` | 設定 | パッケージ依存定義 |
| ivy.el | `modules/completion/ivy/autoload/ivy.el` | ソース | カスタム関数定義 |
| evil.el | `modules/completion/ivy/autoload/evil.el` | ソース | Evil統合 |
| posframe.el | `modules/completion/ivy/autoload/posframe.el` | ソース | Posframe表示関数 |
| doctor.el | `modules/completion/ivy/doctor.el` | ソース | 診断スクリプト |
