# 画面設計書 7-Corfu

## 概要

本ドキュメントは、Doom Emacsのバッファ内補完インターフェース（Corfu）の設計仕様を定義する。

### 本画面の処理概要

Corfuは、エディタバッファ内でテキスト入力時にポップアップ形式で補完候補を表示し、コード補完、テンプレート挿入、単語補完などの機能を提供する。

**業務上の目的・背景**：
Corfuは、Emacs 28+のネイティブ補完インターフェースに基づく軽量なバッファ内補完フレームワークである。Company-modeの代替として、よりシンプルでモダンな設計を採用しており、Emacs標準のcompletion-at-point-functions (capf)と直接連携する。Verticoとの組み合わせで統一的な補完体験を提供する。

**画面へのアクセス方法**：
- テキスト入力中に自動的にポップアップ表示（corfu-auto有効時）
- `C-SPC`（completion-at-point）で手動トリガー
- `TAB`キーでの補完トリガー

**主要な操作・処理内容**：
1. バッファ内補完候補のポップアップ表示
2. fuzzy/部分マッチによる絞り込み
3. LSPバックエンドとの連携（lsp-mode, eglot）
4. cape拡張による追加補完ソース（dabbrev、ファイルパス、絵文字等）
5. ミニバッファへの候補移動（Vertico/Ivy/Helm連携）

**画面遷移**：
- 遷移元：テキスト入力時
- 遷移先：補完候補確定後のバッファ編集継続

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | 入力補完インターフェース（Corfu） | 主機能 | バッファ内補完候補表示、選択、挿入 |
| 48 | バッファ内補完 | 補助機能 | テキスト入力時の補完候補提示 |
| 61 | LSPサポート | 補助機能 | LSPサーバーからの補完候補取得 |

## 画面種別

バッファ内ポップアップ（オーバーレイ/チャイルドフレーム）

## URL/ルーティング

Emacsアプリケーションのため、URLルーティングは存在しない。編集バッファ上のポップアップとして表示される。

## 入出力項目

| 項目名 | 種別 | 必須 | 説明 |
|--------|------|------|------|
| 入力テキスト | 入力 | いいえ | 補完をトリガーするテキスト入力（corfu-auto時は自動、それ以外は手動トリガー） |

## 表示項目

| 項目名 | 種別 | 説明 |
|--------|------|------|
| 候補リスト | 垂直リスト | 補完候補の一覧表示 |
| アイコン | アイコン | 候補の種類を示すアイコン（nerd-icons-corfu使用時） |
| 注釈 | テキスト | 候補の型情報、ソース情報等 |
| カーソル位置 | ハイライト | 現在選択中の候補 |
| ドキュメント | ポップアップ | 選択候補の詳細説明（corfu-popupinfo使用時） |

## イベント仕様

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

| キー | 動作 |
|------|------|
| C-n, 下矢印 | 次の候補へ移動 |
| C-p, 上矢印 | 前の候補へ移動 |
| M-< | 最初の候補へ移動 |
| M-> | 最後の候補へ移動 |
| C-g | 補完をキャンセル |

### 2-選択・確定

| キー | 動作 |
|------|------|
| RET | 選択中の候補を確定（corfu-preselect-first有効時） |
| TAB | 候補を補完/サイクル |
| SPC | セパレーター挿入（orderless使用時） |

### 3-拡張操作

| キー | 動作 |
|------|------|
| M-m | ミニバッファに候補を移動（+corfu/move-to-minibuffer） |
| M-SPC | セパレーター挿入/エスケープ（+corfu/smart-sep-toggle-escape） |
| C-x C-n | Evil complete next（dabbrev） |
| C-x C-p | Evil complete previous（dabbrev） |

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

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

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

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

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容 |
|---------------|---------|---------------|
| 情報 | 自動補完トグル時 | "Corfu auto-complete enabled/disabled" |
| エラー | ミニバッファ移動失敗 | "No minibuffer completion UI available for moving to!" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 補完候補がない | ポップアップを表示しない |
| ミニバッファ補完UIがない | エラーメッセージを表示 |

## 備考

- corfu-autoが有効の場合、指定文字数入力後に自動的にポップアップが表示される
- cape（Completion At Point Extensions）との連携により、複数の補完ソースを統合
- Terminal環境ではcorfu-terminalパッケージを使用

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/completion/corfu/config.el` | 行3-12: corfu-auto, corfu-auto-delay等の設定 |

**読解のコツ**: `corfu-auto`（自動補完）、`corfu-auto-delay`（遅延）、`corfu-auto-prefix`（トリガー文字数）が重要な設定。

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

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

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

**主要処理フロー**:
1. **行14-18**: global-corfu-modeを有効化
2. **行20-35**: corfu設定変数（cycle, preselect等）

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

capeによる補完ソース拡張を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/completion/corfu/config.el` | 行58-80: cape設定 |

**主要処理フロー**:
- cape-dabbrev、cape-file、cape-keyword等の補完ソース設定
- completion-at-point-functionsへの追加

#### Step 4: インタラクティブコマンドを理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload.el | `modules/completion/corfu/autoload.el` | 行12-35: +corfu/move-to-minibuffer関数 |
| 4-2 | autoload.el | `modules/completion/corfu/autoload.el` | 行50-69: +corfu/toggle-auto-complete関数 |
| 4-3 | autoload.el | `modules/completion/corfu/autoload.el` | 行72-99: dabbrev系コマンド |

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

```
テキスト入力
    │
    ├─ corfu-auto有効
    │      └─ post-command-hook → corfu--auto-post-command
    │             └─ corfu-popup表示
    │
    ├─ 手動トリガー（C-SPC）
    │      └─ completion-at-point
    │             └─ corfu-popup表示
    │
    └─ cape（補完ソース）
           ├─ cape-dabbrev（バッファ内単語）
           ├─ cape-file（ファイルパス）
           ├─ cape-keyword（言語キーワード）
           └─ cape-emoji（絵文字）
```

### データフロー図

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

テキスト入力 ────────▶ completion-at-point ───▶ 候補リスト表示

候補選択 + RET ─────▶ corfu-complete ─────────▶ テキスト挿入

M-m押下 ────────────▶ +corfu/move-to-minibuffer ▶ ミニバッファ補完
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/completion/corfu/config.el` | ソース | メイン設定 |
| autoload.el | `modules/completion/corfu/autoload.el` | ソース | インタラクティブコマンド |
| corfu | 外部パッケージ | 依存 | バッファ内補完本体 |
| cape | 外部パッケージ | 依存 | 補完ソース拡張 |
| corfu-terminal | 外部パッケージ | 依存（オプション） | Terminal環境対応 |
| corfu-popupinfo | 外部パッケージ | 依存（オプション） | ドキュメント表示 |
| nerd-icons-corfu | 外部パッケージ | 依存（オプション） | アイコン表示 |
