# 機能設計書 23-Vertico垂直補完フレームワーク

## 概要

本ドキュメントは、Doom EmacsにおけるVertico垂直補完フレームワーク機能の設計を記述する。Verticoは、Emacsのミニバッファにおいて垂直方向の補完候補リストを表示するフレームワークであり、Consult、Embark、Marginaliaなどのパッケージと組み合わせることで、モダンで拡張性の高い補完環境を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Emacsの標準補完システムを強化し、直感的で効率的な操作体験を提供する。Verticoはミニマルな設計思想に基づき、Emacsのネイティブな補完APIを活用することで、軽量かつ高速な動作を実現する。orderless補完スタイルとの組み合わせにより、柔軟なパターンマッチングが可能になる。

**機能の利用シーン**：ファイルを開く際、バッファを切り替える際（`consult-buffer`）、コマンドを実行する際（`execute-extended-command`）、検索を行う際（`consult-line`、`consult-ripgrep`）、シンボルを検索する際（`consult-imenu`）、ブックマークにジャンプする際（`consult-bookmark`）など。

**主要な処理内容**：
1. ミニバッファでの垂直候補リスト表示
2. orderless補完スタイルによる柔軟なマッチング
3. Consult統合による拡張コマンド群
4. Embark統合によるコンテキストアクション
5. Marginalia統合による候補へのアノテーション付加
6. vertico-multiform統合による候補表示のカスタマイズ
7. vertico-posframe（+childframeフラグ有効時）によるポップアップ表示

**関連システム・外部連携**：Consultとの連携による拡張コマンド、Embarkとの連携によるアクション実行、Marginaliaとの連携によるアノテーション表示、Projectileとの連携によるプロジェクト管理、ripgrepとの連携によるテキスト検索。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | Vertico | 主機能 | ミニバッファでの垂直補完候補表示、選択処理 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| 検索クエリ | string | No | インクリメンタル検索のための入力文字列 | 任意の文字列を受け付ける |
| vertico-count | integer | No | 表示する候補数（デフォルト: 17） | 正の整数 |
| consult-async-min-input | integer | No | 非同期検索開始の最小文字数（デフォルト: 2） | 正の整数 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 候補リスト | list | 検索条件に一致する候補のリスト（アノテーション付き） |
| 選択結果 | varies | ユーザーが選択した項目 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. ユーザーがVertico/Consultコマンドを呼び出し
   └─ キーバインドまたはM-xからコマンド実行
2. Verticoセッションの初期化
   └─ vertico-modeによるミニバッファ制御の開始
3. 候補の生成とorderlessマッチング
   └─ completion-stylesに基づく候補フィルタリング
4. Marginaliaによるアノテーション付加
   └─ 候補種別に応じた補足情報の表示
5. インクリメンタル検索ループ
   └─ ユーザー入力に応じた候補絞り込み
6. 候補選択またはEmbarkアクション
   └─ RETで選択、C-;でEmbarkアクション
7. アクションの実行
   └─ 選択された項目に対するアクション実行
8. セッションの終了
   └─ vertico-repeat-saveによるセッション記録
```

### フローチャート

```mermaid
flowchart TD
    A[Vertico/Consultコマンド呼び出し] --> B[vertico-mode初期化]
    B --> C[候補生成]
    C --> D[orderlessマッチング]
    D --> E[Marginaliaアノテーション]
    E --> F{ユーザー入力}
    F -->|文字入力| G[候補絞り込み]
    G --> D
    F -->|RET| H[選択確定]
    F -->|C-;| I[Embarkアクション]
    F -->|C-g| J[キャンセル]
    I --> H
    H --> K[アクション実行]
    K --> L[セッション記録]
    L --> M[終了]
    J --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-23-01 | orderless補完 | スペース区切りで複数パターンの AND 検索 | 常時 |
| BR-23-02 | アフィックスディスパッチ | `!`で除外、`=`で完全一致、`^`で前方一致など | orderless-affix-dispatch-alist |
| BR-23-03 | リモートファイル基本補完 | TRAMPパスでは basic 補完にフォールバック | リモートパス入力時 |
| BR-23-04 | ディレクトリハイライト | スラッシュで終わるパスはディレクトリとしてハイライト | file カテゴリ |

### 計算ロジック

特になし

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

該当なし

## パフォーマンス要件

- `consult-async-min-input`を2に設定し、過度な検索を抑制
- `consult-async-refresh-delay`を0.15秒に設定
- `consult-async-input-throttle`を0.2秒に設定
- `consult-async-input-debounce`を0.1秒に設定
- `vertico-resize`をnilに設定し、不要なウィンドウリサイズを抑制

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

- 外部コマンド（ripgrep、fd）の実行時は、consult-ripgrep-argsで安全な引数構築
- TRAMPリモートパスでの補完時はセキュリティを考慮

## 備考

- Vertico、Ivy、Helmは相互排他的な補完フレームワーク
- Doom Emacsの推奨補完フレームワーク
- Emacs標準の補完APIに準拠した設計

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/completion/vertico/config.el` | メイン設定ファイル、vertico/orderless/consult/embark/marginalia設定 |
| 1-2 | packages.el | `modules/completion/vertico/packages.el` | 依存パッケージの定義 |

**読解のコツ**: `use-package!`の`:preface`と`:config`の違い、`:hook`によるモード有効化タイミングを確認する。

**主要処理フロー**:
- **19-63行目**: vertico本体の設定（候補数、サイクル、キーマッピング）
- **66-101行目**: orderless設定（補完スタイル、ディスパッチャ）
- **104-194行目**: consult設定（非同期検索、バッファソース）
- **263-316行目**: embark設定（アクション、キーマップ）
- **319-339行目**: marginalia設定（アノテーション）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | vertico.el | `modules/completion/vertico/autoload/vertico.el` | カスタム検索、Embark統合、orderlessディスパッチャ |

**主要処理フロー**:
- **8-59行目**: `+vertico-file-search` - ripgrep連携検索の中核
- **83-91行目**: `+vertico-embark-target-package-fn` - Doomパッケージターゲット検出
- **113-138行目**: `+vertico/embark-preview` - プレビュー機能
- **141-185行目**: `+vertico/jump-list` - ジャンプリスト表示
- **246-269行目**: `+vertico-orderless-dispatch` - orderlessディスパッチャ

#### Step 3: 拡張統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/completion/vertico/config.el` | consult-dir、vertico-multiform設定 |
| 3-2 | workspaces.el | `modules/completion/vertico/autoload/workspaces.el` | ワークスペース統合 |
| 3-3 | magit.el | `modules/completion/vertico/autoload/magit.el` | Magit統合 |

**主要処理フロー**:
- **197-251行目**: consult-dir設定（Docker/Podman統合）
- **358-392行目**: vertico-multiform設定（候補表示カスタマイズ）

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

```
execute-extended-command / consult-buffer / consult-find
    │
    ├─ vertico-mode (ミニバッファ制御)
    │      └─ vertico--format-candidate (候補フォーマット)
    │
    ├─ orderless (マッチング)
    │      ├─ orderless-affix-dispatch-alist (ディスパッチャ)
    │      └─ +vertico-orderless-dispatch
    │
    ├─ marginalia-mode (アノテーション)
    │      └─ marginalia-command-categories
    │
    ├─ embark (アクション)
    │      ├─ embark-act
    │      └─ embark-export
    │
    └─ consult (拡張コマンド)
           ├─ consult-ripgrep
           ├─ consult-fd
           └─ consult-buffer
```

### データフロー図

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

ユーザー入力 ───▶ vertico-read ───▶ orderless ───▶ 候補フィルタリング
                      │                              │
                      │                              ▼
                      │                        marginalia
                      │                              │
                      │                              ▼
                      └────────────────────── 候補リスト表示

選択アクション ───▶ embark-act ───▶ コンテキストアクション実行

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

### 関連ファイル一覧

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