# 画面設計書 5-Ivy

## 概要

本ドキュメントは、Doom EmacsのIvy補完インターフェースの設計仕様を定義する。

### 本画面の処理概要

Ivyは、ミニバッファ内で補完候補を表示し、様々なコマンドのインタラクティブな選択を提供する軽量かつ高速な補完フレームワークである。

**業務上の目的・背景**：
Ivyは、Emacs標準の補完機能を拡張し、視覚的で直感的な候補選択を実現する。counsel（コマンド拡張）、swiper（バッファ内検索）と組み合わせることで、強力な検索・ナビゲーション機能を提供する。Verticoの代替として、より成熟した補完エコシステムを求めるユーザーに適している。

**画面へのアクセス方法**：
- 任意の補完を要するコマンド実行時（M-x, find-file, switch-buffer等）
- `SPC f f`（find-file）、`SPC b b`（switch-buffer）等のキーバインド
- `SPC s p`（プロジェクト検索）等

**主要な操作・処理内容**：
1. 補完候補のリスト表示
2. fuzzy/regexp絞り込み検索
3. ライブプレビュー（バッファ切り替え時等）
4. wgrep連携による検索結果の一括編集
5. ivy-rich連携によるリッチな候補表示

**画面遷移**：
- 遷移元：コマンド実行、キーバインド
- 遷移先：選択した候補に対応するバッファ/ファイル/動作

**権限による表示制御**：
- 権限による表示制御は存在しない

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | 入力補完インターフェース（Ivy） | 主機能 | 補完候補のリスト表示、ナビゲーション、選択 |
| 47 | ミニバッファ補完 | 補助機能 | ミニバッファでの補完表示基盤 |
| 3 | コマンドパレット | 補助機能 | M-xでのコマンド選択 |
| 7 | プロジェクト管理 | 補助機能 | プロジェクト内ファイル検索・選択 |
| 50 | ファイル検索 | 補助機能 | counsel-ripgrepによる検索 |

## 画面種別

ミニバッファ補完インターフェース

## URL/ルーティング

Emacsアプリケーションのため、URLルーティングは存在しない。ミニバッファ領域で動作する。

## 入出力項目

| 項目名 | 種別 | 必須 | 説明 |
|--------|------|------|------|
| 検索パターン | 入力 | いいえ | 候補を絞り込むためのテキスト入力 |

## 表示項目

| 項目名 | 種別 | 説明 |
|--------|------|------|
| プロンプト | テキスト | コマンドの説明 |
| 候補リスト | リスト | 絞り込まれた候補の一覧表示 |
| リッチ表示 | テキスト | ivy-richによる候補への付加情報 |
| カーソル位置 | ハイライト | 現在選択中の候補 |
| 候補数 | テキスト | 現在の候補数/全候補数 |

## イベント仕様

### 1-ナビゲーション

| キー | 動作 |
|------|------|
| C-n, 下矢印 | 次の候補へ移動 |
| C-p, 上矢印 | 前の候補へ移動 |
| M-< | 最初の候補へ移動 |
| M-> | 最後の候補へ移動 |
| C-v | ページダウン |
| M-v | ページアップ |

### 2-選択・確定

| キー | 動作 |
|------|------|
| RET | 選択中の候補を確定 |
| TAB | 部分補完 |
| C-m | 確定（RETと同等） |
| C-j | 現在の入力で確定 |

### 3-アクション

| キー | 動作 |
|------|------|
| M-o | 代替アクション選択（ivy-dispatching-done） |
| C-c C-e | wgrepバッファに変換（+ivy/woccur） |

### 4-その他

| キー | 動作 |
|------|------|
| C-' | avy経由で候補を選択 |
| S-SPC | 候補の絞り込みパターンを制限 |

## データベース更新仕様

本画面はEmacs UI機能であり、データベースとの連携は存在しない。

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| なし | - | - | データベース操作なし |

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容 |
|---------------|---------|---------------|
| エラー | ripgrepが見つからない | "Couldn't find ripgrep in your PATH" |
| 情報 | wgrep未対応コマンド | "%S doesn't support wgrep" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ripgrepがインストールされていない | エラーメッセージを表示 |
| wgrep非対応のコマンド | エラーメッセージを表示 |

## 備考

- +fuzzyフラグでflx/prescient等のfuzzyマッチングを有効化可能
- +childframeフラグでivy-posframeを使用した別ウィンドウ表示が可能
- ivy-richにより、バッファ/変数等に追加情報を表示

---

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

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

### 推奨読解順序

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

Ivyの設定変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/completion/ivy/config.el` | 行3-21: 変数定義（+ivy-buffer-preview, +ivy-edit-functions等） |

**読解のコツ**: `+ivy-buffer-preview`はバッファプレビュー動作を制御、`+ivy-edit-functions`は各コマンド用のwgrep変換関数をマッピング。

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

ivyの基本設定を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/completion/ivy/config.el` | 行37-78: ivy設定 |

**主要処理フロー**:
1. **行39-43**: ivy-modeを有効化
2. **行44-60**: ivy設定変数（ivy-height, ivy-wrap, ivy-use-virtual-buffers等）
3. **行62-70**: ivy-format-function設定（Terminal時はarrow形式）

#### Step 3: Counsel連携を理解する

counselによるコマンド拡張を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/completion/ivy/config.el` | 行102-170: counsel設定 |

**主要処理フロー**:
- **行102-170**: counsel-rg, counsel-compile等の設定

#### Step 4: Ivy-rich連携を理解する

ivy-richによるリッチ表示を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/completion/ivy/config.el` | 行172-260: ivy-rich設定 |

**主要処理フロー**:
- **行172-260**: 各候補タイプに対するトランスフォーマー設定

#### Step 5: 検索コマンドを理解する

Doom固有の検索コマンドを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | autoload/ivy.el | `modules/completion/ivy/autoload/ivy.el` | 行240-282: +ivy-file-search関数 |
| 5-2 | autoload/ivy.el | `modules/completion/ivy/autoload/ivy.el` | 行285-299: +ivy/project-search関数 |

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

```
ユーザー入力（M-x, SPC f f等）
    │
    ├─ ivy-mode
    │      └─ 候補のリスト表示
    │
    ├─ counsel（コマンド系）
    │      ├─ counsel-M-x（コマンド実行）
    │      ├─ counsel-find-file（ファイル選択）
    │      └─ counsel-rg（ripgrep検索）
    │
    ├─ swiper（検索系）
    │      └─ バッファ内行検索
    │
    └─ ivy-rich
           └─ 候補にリッチ情報追加
```

### データフロー図

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

検索パターン ────────▶ ivy ─────────────────▶ 絞り込まれた候補

候補リスト ─────────▶ ivy-rich ─────────────▶ リッチ表示候補

grep結果 + C-c C-e ─▶ +ivy/woccur ──────────▶ wgrepバッファ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/completion/ivy/config.el` | ソース | メイン設定 |
| autoload/ivy.el | `modules/completion/ivy/autoload/ivy.el` | ソース | 検索・バッファ切り替えコマンド |
| autoload/evil.el | `modules/completion/ivy/autoload/evil.el` | ソース | Evil連携 |
| autoload/posframe.el | `modules/completion/ivy/autoload/posframe.el` | ソース | posframe連携 |
| ivy | 外部パッケージ | 依存 | 補完本体 |
| counsel | 外部パッケージ | 依存 | コマンド拡張 |
| swiper | 外部パッケージ | 依存 | バッファ内検索 |
| ivy-rich | 外部パッケージ | 依存 | リッチ表示 |
| ivy-posframe | 外部パッケージ | 依存（オプション） | childframe表示 |
