# 画面設計書 8-Company

## 概要

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

### 本画面の処理概要

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

**業務上の目的・背景**：
Company-mode（Complete Anything）は、Emacsで最も広く使用されているバッファ内補完フレームワークである。多数のバックエンド（company-capf、company-dabbrev、company-yasnippet等）を通じて様々な補完ソースをサポートし、LSPクライアント（lsp-mode、eglot）との連携も充実している。Corfuの代替として、より成熟したエコシステムと広範なカスタマイズ性を提供する。

**画面へのアクセス方法**：
- テキスト入力中に自動的にポップアップ表示（company-idle-delay設定に基づく）
- `C-SPC`または設定されたキーで手動トリガー
- `M-/`（dabbrev-expand）の代替として

**主要な操作・処理内容**：
1. バッファ内補完候補のポップアップ表示
2. 複数バックエンドからの候補統合
3. LSPバックエンドとの連携
4. company-boxによるリッチなUIの提供（childframeフラグ時）
5. company-dictによるカスタム辞書補完

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

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

## 関連機能

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

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

| 項目名 | 種別 | 必須 | 説明 |
|--------|------|------|------|
| 入力テキスト | 入力 | いいえ | 補完をトリガーするテキスト入力（company-idle-delay後に自動、または手動トリガー） |

## 表示項目

| 項目名 | 種別 | 説明 |
|--------|------|------|
| 候補リスト | 垂直リスト | 補完候補の一覧表示（最大14件） |
| アイコン | アイコン | 候補の種類を示すアイコン（company-box使用時、nerd-icons対応） |
| 注釈 | テキスト | 候補の型情報、バックエンド情報等 |
| カーソル位置 | ハイライト | 現在選択中の候補 |
| メタデータ | エコーエリア | 選択候補の詳細説明 |

## イベント仕様

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

| キー | 動作 |
|------|------|
| C-n, 下矢印 | 次の候補へ移動 |
| C-p, 上矢印 | 前の候補へ移動 |
| M-n | 次ページへ移動 |
| M-p | 前ページへ移動 |
| C-g, ESC | 補完をキャンセル |

### 2-選択・確定

| キー | 動作 |
|------|------|
| RET | 選択中の候補を確定 |
| TAB | 共通部分を補完 |
| C-h | 選択候補のドキュメント表示 |

### 3-バックエンド切り替え

| キー | 動作 |
|------|------|
| C-x C-s | yasnippetバックエンドに切り替え |
| C-x C-n | dabbrev-codeバックエンドに切り替え |

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

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

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

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

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容 |
|---------------|---------|---------------|
| 情報 | 自動補完トグル時 | "Auto completion enabled/disabled" |
| エコーエリア | 候補選択時 | 選択候補のメタデータ表示 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 補完候補がない | ポップアップを表示しない |
| バックエンドエラー | 次のバックエンドを試行 |

## 備考

- company-idle-delayが設定時間（MacOS: 0.4s、その他: 0.26s）経過後に自動補完
- company-minimum-prefix-lengthで補完トリガーの最小文字数（デフォルト: 2）を制御
- company-dabbrev-other-buffersはnilに設定され、現在のバッファのみから候補を取得
- Evilモード対応として、ノーマルステート突入時にcompany-abortが呼ばれる

---

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

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

### 推奨読解順序

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

Companyの設定変数とバックエンド定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/completion/company/config.el` | 行3-45: company設定変数 |
| 1-2 | autoload.el | `modules/completion/company/autoload.el` | 行4-9: +company-backend-alist変数 |

**読解のコツ**: `company-backends`（バックエンド優先順）、`company-idle-delay`（自動補完遅延）、`company-minimum-prefix-length`（トリガー文字数）が重要。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/completion/company/config.el` | 行3-45: use-package! company設定 |

**主要処理フロー**:
1. **行8**: doom-first-input-hookでglobal-company-mode有効化
2. **行10-17**: 基本設定（prefix-length, tooltip-limit, idle-delay等）
3. **行18-24**: company-global-modes設定（除外モード指定）
4. **行47-48**: +tngフラグ時にcompany-tng-mode有効化

#### Step 3: Evilモード連携を理解する

Evil対応の設定を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/completion/company/config.el` | 行51-66: Evil連携設定 |

**主要処理フロー**:
- **行51-60**: evil-normal-state突入時にcompany-abort
- **行64-66**: バックエンド切り替え時に前のセッションをabort

#### Step 4: Company-box連携を理解する

リッチUI（childframe）の設定を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/completion/company/config.el` | 行97-176: company-box設定 |

**主要処理フロー**:
- **行101-142**: nerd-iconsによるアイコン定義（各候補タイプ別）
- **行157-163**: ElispFunction/Variable/Feature/Faceアイコン判定関数

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | autoload.el | `modules/completion/company/autoload.el` | 行67-73: +company-init-backends-h関数 |
| 5-2 | autoload.el | `modules/completion/company/autoload.el` | 行90-96: +company/toggle-auto-completion関数 |
| 5-3 | autoload.el | `modules/completion/company/autoload.el` | 行160-172: +company/completing-read関数 |

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

```
テキスト入力
    │
    ├─ company-idle-delay経過
    │      └─ company-auto-begin → company-popup表示
    │
    ├─ 手動トリガー（+company/complete等）
    │      └─ company-manual-begin → company-popup表示
    │
    └─ company-backends
           ├─ company-capf（completion-at-point）
           ├─ company-dabbrev（バッファ内単語）
           ├─ company-yasnippet（スニペット）
           └─ company-dict（辞書補完）
```

### データフロー図

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

テキスト入力 ────────▶ company-backends ──────▶ 候補リスト表示

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

+company/complete ──▶ company-manual-begin ──▶ 補完セッション開始
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/completion/company/config.el` | ソース | メイン設定 |
| autoload.el | `modules/completion/company/autoload.el` | ソース | バックエンド管理、コマンド |
| company | 外部パッケージ | 依存 | バッファ内補完本体 |
| company-box | 外部パッケージ | 依存（オプション） | childframe UI |
| company-dict | 外部パッケージ | 依存 | 辞書補完 |
| company-prescient | 外部パッケージ | 依存（オプション） | ソート・フィルタリング |
