# 機能設計書 21-Helm補完・ナビゲーションフレームワーク

## 概要

本ドキュメントは、Doom EmacsにおけるHelm補完・ナビゲーションフレームワーク機能の設計を記述する。Helmは、Emacs上でインクリメンタル検索と補完を提供する強力なフレームワークであり、ファイル検索、バッファ切り替え、コマンド実行など多岐にわたる機能を統一的なインターフェースで提供する。

### 本機能の処理概要

**業務上の目的・背景**：開発者は日常的にファイルの検索、バッファの切り替え、コマンドの実行など多様な操作を行う。これらの操作を効率化し、キーボードから手を離さずに高速な操作を可能にするため、統一された補完インターフェースが必要とされる。Helmはこのニーズに応え、インクリメンタルな絞り込み検索により、大量の候補から目的の項目を素早く見つけ出すことができる。

**機能の利用シーン**：ファイルを開く際（`helm-find-files`）、バッファを切り替える際（`helm-buffers-list`）、コマンドを実行する際（`helm-M-x`）、プロジェクト内のファイルを検索する際（`helm-projectile-find-file`）、テキストを検索する際（`helm-rg`によるripgrep検索）など、エディタ操作のあらゆる場面で活用される。

**主要な処理内容**：
1. ミニバッファでのインクリメンタル検索インターフェースの表示
2. 入力に応じた候補のリアルタイム絞り込み
3. ファジーマッチング（+fuzzyフラグ有効時）による柔軟な検索
4. Projectile連携によるプロジェクト単位のファイル・バッファ管理
5. ripgrep連携によるプロジェクト横断テキスト検索
6. ワークスペース連携によるバッファの分離管理
7. childframe（+childframeフラグ有効時）によるポップアップ表示

**関連システム・外部連携**：Projectileとの連携によるプロジェクト管理、ripgrepとの連携によるテキスト検索、persp-modeとの連携によるワークスペース管理、posframeとの連携によるchildframe表示を行う。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Helm | 主機能 | 多機能インクリメンタル検索・選択 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| 検索クエリ | string | No | インクリメンタル検索のための入力文字列 | 任意の文字列を受け付ける |
| helm-candidate-number-limit | integer | No | 表示する候補数の上限（デフォルト: 150） | 正の整数 |
| fuzzy-match | boolean | No | ファジーマッチングの有効/無効 | +fuzzyフラグで制御 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 候補リスト | list | 検索条件に一致する候補のリスト |
| 選択結果 | varies | ユーザーが選択した項目（ファイルパス、バッファ、コマンド等） |

### 出力先

- ミニバッファまたはchildframe（候補表示）
- 選択されたアクションに応じた出力先（ファイルオープン、バッファ切り替え等）

## 処理フロー

### 処理シーケンス

```
1. ユーザーがHelmコマンドを呼び出し
   └─ キーバインドまたはM-xからコマンド実行
2. Helmセッションの初期化
   └─ ミニバッファまたはchildframeの準備
3. 候補ソースの読み込み
   └─ コマンドに応じた候補データの取得
4. インクリメンタル検索ループ
   └─ ユーザー入力に応じて候補を絞り込み
5. 候補の選択
   └─ RETで選択、TABでアクション選択
6. アクションの実行
   └─ 選択された項目に対するアクション実行
7. Helmセッションの終了
   └─ クリーンアップ処理
```

### フローチャート

```mermaid
flowchart TD
    A[Helmコマンド呼び出し] --> B[セッション初期化]
    B --> C[候補ソース読み込み]
    C --> D{ユーザー入力}
    D -->|文字入力| E[候補絞り込み]
    E --> D
    D -->|RET| F[選択確定]
    D -->|C-g| G[キャンセル]
    F --> H[アクション実行]
    H --> I[セッション終了]
    G --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-21-01 | 候補数制限 | 表示候補数は`helm-candidate-number-limit`（150）に制限 | 常時 |
| BR-21-02 | ファジーマッチ | +fuzzyフラグ有効時、部分一致や順序無視の検索が可能 | +fuzzyモジュールフラグ有効時 |
| BR-21-03 | プロジェクト優先 | ホームディレクトリからの検索時はhelm-find-filesにフォールバック | HOMEまたはプロジェクトルートがHOMEの場合 |

### 計算ロジック

特になし

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ERR-21-01 | ripgrep未検出 | ripgrep実行ファイルが見つからない | ユーザーにripgrepのインストールを促す |
| ERR-21-02 | ワークスペースモジュール未有効 | workspace-buffer-listコマンド使用時にワークスペースモジュールが無効 | user-errorでモジュール有効化を促す |

### リトライ仕様

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

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

該当なし

## パフォーマンス要件

- 候補数上限を150に設定し、大量候補でのパフォーマンス低下を防止
- `ivy-sort-max-size`相当の制限はないが、ファイル数の多いプロジェクトでは`projectile-find-file`へのフォールバックを推奨

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

- 外部コマンド（ripgrep）の実行時は、ユーザー入力を適切にエスケープ
- シェル環境変数の露出リスクはない

## 備考

- Helm、Ivy、Verticoは相互排他的な補完フレームワークであり、通常は1つのみを有効にする
- Doom Emacsでは`completion/helm`モジュールを有効にすることで利用可能

---

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

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

### 推奨読解順序

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

Helmモジュールの設定は`config.el`で行われる。変数定義とuse-package!マクロによるパッケージ設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/completion/helm/config.el` | Helmの初期設定、キーバインド定義、各種オプション設定 |
| 1-2 | packages.el | `modules/completion/helm/packages.el` | 依存パッケージの定義 |

**読解のコツ**: `use-package!`マクロはDoom独自のパッケージ設定マクロ。`:hook`、`:config`、`:init`セクションの役割を理解すること。

**主要処理フロー**:
- **4-19行目**: childframe用変数定義（`+helm-posframe-handler`等）
- **24-28行目**: helm-modeの初期化、`doom-first-input`フックで有効化
- **31-105行目**: helm本体の設定（候補数制限、UIオプション、キーマッピング）
- **50-66行目**: 標準コマンドのHelmコマンドへのリマップ定義

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

Helm拡張機能として定義された自動ロード関数群を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | helm.el | `modules/completion/helm/autoload/helm.el` | カスタム検索関数、ワークスペース連携 |
| 2-2 | evil.el | `modules/completion/helm/autoload/evil.el` | Evil統合用のExコマンド定義 |

**主要処理フロー**:
- **4-14行目**: `+helm/projectile-find-file` - HOMEからの呼び出し判定ロジック
- **17-34行目**: ワークスペースバッファリスト関数
- **41-69行目**: `+helm-file-search` - ripgrep連携検索の中核処理
- **72-94行目**: プロジェクト検索のラッパー関数

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

Evil（Vimエミュレーション）との統合部分を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | evil.el | `modules/completion/helm/autoload/evil.el` | Exコマンド定義、プロンプト表示カスタマイズ |

**主要処理フロー**:
- **5-8行目**: `+helm:project-search` Exコマンド定義
- **17-42行目**: `+helm--set-prompt-display` - Evilステート表示のカスタマイズ

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

```
helm-M-x / helm-find-files / helm-buffers-list
    │
    ├─ helm-mode (初期化)
    │      └─ helm-completing-read-handlers-alist (ハンドラ設定)
    │
    ├─ +helm/projectile-find-file
    │      ├─ doom-project-root (プロジェクトルート取得)
    │      └─ helm-projectile-find-file / helm-find-files
    │
    └─ +helm-file-search
           ├─ helm-rg (ripgrep実行)
           └─ doom-project-root
```

### データフロー図

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

ユーザー入力 ───▶ helm-read ───▶ 候補フィルタリング ───▶ 候補リスト表示
                      │
ファイルシステム ───▶ helm-source ───▶ 候補生成
                      │
ripgrep結果 ───────▶ helm-rg-source ───▶ 検索結果候補

選択アクション ───▶ helm-action ───▶ ファイルオープン/バッファ切替/コマンド実行
```

### 関連ファイル一覧

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