# 画面設計書 6-Helm

## 概要

本ドキュメントは、Doom EmacsのHelm補完インターフェースの設計仕様を定義する。

### 本画面の処理概要

Helmは、Emacsの高機能なインクリメンタル補完フレームワークであり、多様なソースからの候補を統合的に検索・選択する機能を提供する。

**業務上の目的・背景**：
Helmは、最も成熟したEmacs補完フレームワークの一つであり、豊富な機能と広範なエコシステムを持つ。バッファ、ファイル、コマンド、変数、シンボルなど、あらゆる種類の候補を統一的なインターフェースで検索・選択できる。Vertico/Ivyの代替として、より多機能な補完システムを求めるユーザーに適している。

**画面へのアクセス方法**：
- 任意の補完を要するコマンド実行時（M-x, find-file, switch-buffer等）
- `SPC f f`（find-file）、`SPC b b`（switch-buffer）等のキーバインド
- `SPC s p`（プロジェクト検索）等

**主要な操作・処理内容**：
1. 補完候補のリスト表示
2. パターンによる絞り込み検索
3. 複数ソースからの統合検索
4. helm-rgによるripgrep検索
5. helm-projectile連携によるプロジェクトファイル操作

**画面遷移**：
- 遷移元：コマンド実行、キーバインド
- 遷移先：選択した候補に対応するバッファ/ファイル/動作

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | 入力補完インターフェース（Helm） | 主機能 | 補完候補のリスト表示、ナビゲーション、選択 |
| 47 | ミニバッファ補完 | 補助機能 | ミニバッファでの補完表示基盤 |
| 3 | コマンドパレット | 補助機能 | M-xでのコマンド選択 |
| 7 | プロジェクト管理 | 補助機能 | helm-projectile連携 |
| 50 | ファイル検索 | 補助機能 | helm-rgによる検索 |

## 画面種別

ミニバッファ補完インターフェース / 専用バッファ

## URL/ルーティング

Emacsアプリケーションのため、URLルーティングは存在しない。Helmウィンドウで動作する。

## 入出力項目

| 項目名 | 種別 | 必須 | 説明 |
|--------|------|------|------|
| 検索パターン | 入力 | いいえ | 候補を絞り込むためのテキスト入力 |

## 表示項目

| 項目名 | 種別 | 説明 |
|--------|------|------|
| ヘッダー | テキスト | ソース名表示 |
| 候補リスト | リスト | 絞り込まれた候補の一覧表示 |
| カーソル位置 | ハイライト | 現在選択中の候補 |
| モードライン | テキスト | 候補数、パターン等の情報 |

## イベント仕様

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

| キー | 動作 |
|------|------|
| C-n, 下矢印 | 次の候補へ移動 |
| C-p, 上矢印 | 前の候補へ移動 |
| M-< | 最初の候補へ移動 |
| M-> | 最後の候補へ移動 |
| C-v, next | ページダウン |
| M-v, prior | ページアップ |
| C-c o | 次のソースへ移動 |

### 2-選択・確定

| キー | 動作 |
|------|------|
| RET | 選択中の候補を確定 |
| TAB | 補完 |
| C-j | 永続アクション（候補を実行しつつセッション継続） |

### 3-アクション

| キー | 動作 |
|------|------|
| C-z | 候補のアクション一覧を表示 |
| M-a | すべての候補を選択 |
| C-SPC | 候補をマーク |

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

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

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

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

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容 |
|---------------|---------|---------------|
| エラー | ripgrepが見つからない | "Couldn't find ripgrep in your PATH" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ripgrepがインストールされていない | エラーメッセージを表示 |
| HOMEディレクトリからの呼び出し | helm-find-filesにフォールバック |

## 備考

- helm-projectileによりprojectileプロジェクト操作と連携
- +childframeフラグでhelm-posframeを使用した別ウィンドウ表示が可能
- helm-swoop等の拡張パッケージで機能拡張可能

---

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

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

### 推奨読解順序

#### Step 1: 基本設定を理解する

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

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

**読解のコツ**: `helm-display-buffer-default-height`, `helm-split-window-inside-p`等が表示を制御。

#### Step 2: helm-projectile連携を理解する

projectileとの連携設定を把握する。

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

**主要処理フロー**:
- helm-projectile-fuzzy-matchの設定
- ワークスペースとの連携（+workspacesモジュール時）

#### Step 3: 検索コマンドを理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | autoload/helm.el | `modules/completion/helm/autoload/helm.el` | 行4-14: +helm/projectile-find-file関数 |
| 3-2 | autoload/helm.el | `modules/completion/helm/autoload/helm.el` | 行41-69: +helm-file-search関数 |
| 3-3 | autoload/helm.el | `modules/completion/helm/autoload/helm.el` | 行72-94: +helm/project-search関数 |

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

```
ユーザー入力（M-x, SPC f f等）
    │
    ├─ helm-mode
    │      └─ 候補のリスト表示
    │
    ├─ helm-projectile
    │      ├─ helm-projectile-find-file
    │      └─ helm-projectile-switch-project
    │
    └─ helm-rg
           └─ ripgrepによるプロジェクト検索
```

### データフロー図

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

検索パターン ────────▶ helm ─────────────────▶ 絞り込まれた候補

プロジェクト選択 ────▶ helm-projectile ──────▶ プロジェクトファイル一覧

grep検索 ───────────▶ helm-rg ───────────────▶ 検索結果表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/completion/helm/config.el` | ソース | メイン設定 |
| autoload/helm.el | `modules/completion/helm/autoload/helm.el` | ソース | 検索・ナビゲーションコマンド |
| autoload/evil.el | `modules/completion/helm/autoload/evil.el` | ソース | Evil連携 |
| helm | 外部パッケージ | 依存 | 補完本体 |
| helm-projectile | 外部パッケージ | 依存 | projectile連携 |
| helm-rg | 外部パッケージ | 依存 | ripgrep検索 |
| helm-posframe | 外部パッケージ | 依存（オプション） | childframe表示 |
