# 機能設計書 20-corfu

## 概要

本ドキュメントは、Doom Emacsの軽量テキスト補完モジュール「corfu」の機能設計を定義する。このモジュールは、corfuパッケージを使用したインラインポップアップ形式のコード補完機能を提供する。

### 本機能の処理概要

corfuモジュールは、Emacs用の軽量テキスト補完フレームワークであるcorfu.elをDoom Emacs向けに設定・拡張したものである。completion-at-point-functions（CAPF）をベースとした補完システムを採用し、モダンで軽量な補完UIを提供する。

**業務上の目的・背景**：corfuはcompany-modeの代替として開発された軽量な補完フレームワークである。Emacsの組み込みのcompletion-at-point-functions（CAPF）システムを直接活用するため、より標準的でシンプルなアーキテクチャを持つ。また、verticoやconsultなどの同じ作者によるパッケージとの親和性が高く、一貫したユーザー体験を提供する。Doomのcorfuモジュールは、cape（Completion At Point Extensions）との統合、Evil対応、ミニバッファ補完などの拡張機能を提供する。

**機能の利用シーン**：
- コード入力中の変数名・関数名補完
- ファイルパスの補完（cape-file）
- バッファ内テキストの補完（cape-dabbrev）
- スニペットの補完（yasnippet-capf）
- Orgモード・Markdownでのelispブロック補完

**主要な処理内容**：
1. corfu-modeのグローバル有効化（doom-first-inputフック）
2. capeによる追加capf関数の登録
3. RET/TABキーの挙動カスタマイズ
4. ミニバッファでの補完サポート
5. corfu-history/corfu-popupinfoの統合
6. nerd-icons-corfuによるアイコン表示（+iconsフラグ）

**関連システム・外部連携**：
- LSP（lsp-mode/eglot）: 言語サーバー補完
- yasnippet: スニペット補完
- cape: 追加のcapf関数群
- orderless: ファジーマッチング

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | Corfu | 主機能 | インラインコード補完ポップアップ表示 |
| 7 | Corfu | 補助機能 | yasnippet-capf連携によるスニペット補完 |
| 7 | Corfu | API連携 | lsp-completion-at-point連携 |

## 機能種別

テキスト補完 / UI拡張 / 入力支援

## 入力仕様

### 入力パラメータ

モジュールフラグ:
| フラグ名 | 説明 |
|---------|------|
| +icons | nerd-icons-corfuによるアイコン表示を有効化 |
| +orderless | orderlessによるファジーマッチングを有効化 |
| +dabbrev | cape-dabbrevによるバッファ補完を有効化 |

### 入力データソース

- completion-at-point-functions: 各モードのcapf関数群
- cape: 追加のcapf関数（cape-file, cape-dabbrev, cape-elisp-block等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 補完候補リスト | リスト | マッチした補完候補の一覧 |
| ポップアップ情報 | 文字列 | 選択中の候補のドキュメント（popupinfo） |

### 出力先

- 補完ポップアップ（インライン表示）
- ドキュメントポップアップ（corfu-popupinfo）

## 処理フロー

### 処理シーケンス

```
1. トリガー検出
   └─ corfu-auto-delay経過後に自動起動
   └─ またはTABキーによる手動起動

2. completion-at-point呼び出し
   └─ completion-at-point-functionsの各関数を順次実行

3. 候補取得
   └─ 各capf関数から候補を取得
   └─ capeによるラップ処理（nonexclusive等）

4. 候補表示
   └─ corfuポップアップで表示
   └─ corfu-popupinfoでドキュメント表示

5. 選択・確定
   └─ C-n/C-pまたはM-{n}で選択
   └─ RETまたはTABで確定
```

### フローチャート

```mermaid
flowchart TD
    A[入力開始] --> B{アイドル<br>タイムアウト?}
    B -->|Yes| C[completion-at-point]
    B -->|No| D{TAB押下?}
    D -->|Yes| C
    D -->|No| A
    C --> E[capf関数実行]
    E --> F{候補<br>あり?}
    F -->|No| G[補完中止]
    F -->|Yes| H[ポップアップ表示]
    H --> I{選択?}
    I -->|確定| J[テキスト挿入]
    I -->|キャンセル| G
    I -->|継続入力| C
    I -->|スニペット?| K[スニペット展開]
    G --> A
    J --> A
    K --> A
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 自動補完遅延 | MacOS: 0.4秒、その他: 0.24秒 | corfu-auto-delay |
| BR-02 | 最小プレフィックス | 2文字以上で補完開始 | corfu-auto-prefix |
| BR-03 | RET挙動 | +corfu-want-ret-to-confirmで設定可能 | RETキー押下時 |
| BR-04 | ミニバッファ補完 | +corfu-want-minibuffer-completionで制御 | ミニバッファ内 |
| BR-05 | バッファスキャン制限 | 1MB超のバッファはdabbrevスキャン対象外 | +corfu-buffer-scanning-size-limit |

### 設定値

```elisp
corfu-auto t
corfu-cycle t
corfu-preselect 'prompt
corfu-count 16
corfu-max-width 120
corfu-on-exact-match nil
corfu-quit-at-boundary 'separator  ; verticoまたは+orderless時
tab-always-indent 'complete
corfu-auto-delay (if (featurep :system 'macos) 0.4 0.24)
corfu-auto-prefix 2
```

### 計算ロジック

**ミニバッファ補完判定（+corfu-enable-in-minibuffer-p）**:
```elisp
(defun +corfu-enable-in-minibuffer-p ()
  (pcase +corfu-want-minibuffer-completion
    ('nil nil)
    ('aggressive (not (+corfu--other-completion-active-p)))
    (_ (and (where-is-internal #'completion-at-point
                               (list (current-local-map)))
            (not (+corfu--other-completion-active-p))))))
```

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ispellエラー | 辞書が設定されていない | 一度だけ警告し、ispell-capfを無効化 |

### リトライ仕様

特になし。

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

補完はステートレスな処理のため、トランザクション管理は不要。

## パフォーマンス要件

- +corfu-buffer-scanning-size-limit: 1MB超のバッファはdabbrevスキャン対象外
- cape-wrap-noninterruptible: LSP補完の中断を防止
- corfu-auto-delay: MacOSでは0.4秒に調整

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

特になし。

## 備考

- companyモジュールとは排他的に使用（同時有効化は非推奨）
- verticoモジュールとの併用が推奨される
- corfu-historyでsavehistと統合

---

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

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

### 推奨読解順序

#### Step 1: カスタマイズ変数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/completion/corfu/config.el` | 3-34行目のdefvar定義 |

**読解のコツ**: `+corfu-want-*`変数はユーザーがRET/TAB/ミニバッファの挙動をカスタマイズするためのもの。`+corfu-inhibit-auto-functions`は自動補完を抑制する条件を定義するフックリスト。

**主要変数**:
- **3-9行目**: +corfu-want-ret-to-confirm - RETキーの挙動
- **11-12行目**: +corfu-buffer-scanning-size-limit - dabbrevスキャン制限
- **14-17行目**: +corfu-want-minibuffer-completion - ミニバッファ補完
- **31-34行目**: +corfu-inhibit-auto-functions - 自動補完抑制条件

#### Step 2: corfu設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/completion/corfu/config.el` | 40-135行目のcorfu use-package! |

**主要処理フロー**:
- **40-41行目**: doom-first-inputでglobal-corfu-mode
- **43-60行目**: 基本設定（corfu-auto, corfu-cycle等）
- **67-82行目**: +corfu--other-completion-active-p - 他補完フレームワーク検出
- **86-100行目**: +corfu-enable-in-minibuffer-p - ミニバッファ補完判定

#### Step 3: cape統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/completion/corfu/config.el` | 162-210行目のcape use-package! |

**主要処理フロー**:
- **165-167行目**: cape-file - prog-modeでファイルパス補完
- **168-170行目**: cape-elisp-block - org/markdownでelispブロック補完
- **172-191行目**: cape-dabbrev - +dabbrevフラグ時のdabbrev補完
- **194-198行目**: capeラッパー（noninterruptible, nonexclusive）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/completion/corfu/config.el` | 229-255行目の拡張機能 |

**主要処理フロー**:
- **229-232行目**: corfu-history - 補完履歴
- **234-237行目**: corfu-popupinfo - ドキュメントポップアップ
- **239-244行目**: nerd-icons-corfu - アイコン表示

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | autoload.el | `modules/completion/corfu/autoload.el` | 1-101行目のコマンド |

**主要処理フロー**:
- **12-35行目**: +corfu/move-to-minibuffer - ミニバッファへ移動
- **38-47行目**: +corfu/smart-sep-toggle-escape - セパレータトグル
- **58-69行目**: +corfu/toggle-auto-complete - 自動補完トグル
- **72-99行目**: +corfu/dabbrev-or-next/last - evil-complete風の補完

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

```
global-corfu-mode
    │
    └─ corfu-mode (各バッファ)
           │
           ├─ completion-at-point-functions
           │      ├─ cape-file
           │      ├─ cape-dabbrev (+dabbrev)
           │      ├─ cape-elisp-block (org/markdown)
           │      ├─ yasnippet-capf (+snippets)
           │      └─ lsp-completion-at-point (LSP)
           │
           ├─ corfu--popup-support-p
           │      └─ +corfu-inhibit-auto-functions
           │
           └─ 拡張機能
                  ├─ corfu-history-mode
                  ├─ corfu-popupinfo-mode
                  └─ nerd-icons-corfu-formatter
```

### データフロー図

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

キー入力            ───▶  corfu--auto-post-command ───▶  補完開始判定

completion-at-      ───▶  各capf関数実行 ───▶  候補リスト
point-functions            │
                           ├─ cape-file
                           ├─ cape-dabbrev
                           └─ lsp-capf

候補リスト          ───▶  corfu表示    ───▶  ポップアップ

corfu-history       ───▶  履歴保存    ───▶  savehist

選択               ───▶  挿入/展開   ───▶  バッファ更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/completion/corfu/config.el` | ソース | 主設定ファイル |
| autoload.el | `modules/completion/corfu/autoload.el` | ソース | 自動ロード関数 |
| packages.el | `modules/completion/corfu/packages.el` | 設定 | パッケージ定義 |
| corfu.el | (外部パッケージ) | ソース | corfu本体 |
| cape.el | (外部パッケージ) | ソース | 追加capf関数群 |
| nerd-icons-corfu.el | (外部パッケージ) | ソース | アイコンフォーマッタ |
| yasnippet-capf.el | (外部パッケージ) | ソース | スニペットcapf |
| corfu-terminal.el | (外部パッケージ) | ソース | TTY対応 |
