# 機能設計書 57-スペルチェック

## 概要

本ドキュメントは、Doom Emacsの`checkers/spell`モジュールが提供するスペルチェック機能の設計仕様を記述する。aspell、hunspell、enchantなどのスペルチェッカーと連携し、flyspellまたはspell-fuによるリアルタイムスペルチェック、修正提案、辞書管理機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：ドキュメント作成やコメント記述において、スペルミスは信頼性を損なう要因となる。リアルタイムでスペルチェックを行い、視覚的なフィードバックと修正提案を提供することで、品質の高いテキストを効率的に作成できるようにする。

**機能の利用シーン**：
- Markdown、Org-mode、LaTeXでの文書作成
- プログラムのコメント・ドキュメント記述
- メール作成（mu4e、message-mode）
- Gitコミットメッセージの作成

**主要な処理内容**：
1. flyspell/spell-fuによるリアルタイムスペルチェック
2. aspell、hunspell、enchantへの委譲
3. 修正候補の表示（Ivy/Helm/Vertico統合）
4. 個人辞書・セッション辞書への単語追加
5. 特定のフェイス（コードブロック等）のスキップ

**関連システム・外部連携**：
- aspell/hunspell/enchant（外部スペルチェッカー）
- flyspell（Emacs組み込みスペルチェック）
- spell-fu（高速代替実装）
- flyspell-correct（修正UI）
- flyspell-lazy（遅延チェック）

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | テキスト編集バッファ | 主画面 | スペルミスのハイライト表示、修正操作 |

## 機能種別

テキスト検証 / 修正支援

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| -flyspell | flag | No | spell-fuを使用（flyspellの代わり） | modulep!でチェック |
| +aspell | flag | No | aspellを強制使用 | modulep!でチェック |
| +hunspell | flag | No | hunspellを強制使用 | modulep!でチェック |
| +enchant | flag | No | enchantを強制使用 | modulep!でチェック |
| +everywhere | flag | No | プログラミングモードでもチェック | modulep!でチェック |

### 入力データソース

- バッファのテキスト内容
- ispell辞書ファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| スペルミスハイライト | overlay | 誤りのある単語のハイライト |
| 修正候補 | list | スペル修正の候補リスト |

### 出力先

- 現在のバッファ（オーバーレイ）
- 修正候補選択UI（Ivy/Helm/Vertico/ポップアップ）

## 処理フロー

### 処理シーケンス

```
1. テキストモードでバッファを開く
   └─ flyspell-mode または spell-fu-mode が有効化
2. テキスト入力/編集
   └─ リアルタイムでスペルチェック実行
3. スペルミス検出
   └─ 単語にオーバーレイを適用（ハイライト）
4. ユーザーが修正を要求
   └─ +spell/correct または flyspell-correct-at-point
5. 修正候補を表示
   └─ Ivy/Helm/Vertico/popup UIで選択
6. 修正適用または辞書追加
```

### フローチャート

```mermaid
flowchart TD
    A[バッファを開く] --> B{テキストモード?}
    B -->|Yes| C{-flyspellフラグ?}
    B -->|No| D{+everywhere?}
    D -->|Yes| E[flyspell-prog-mode]
    D -->|No| F[スペルチェックなし]
    C -->|Yes| G[spell-fu-mode]
    C -->|No| H[flyspell-mode]
    G --> I[リアルタイムチェック]
    H --> I
    E --> I
    I --> J{スペルミス?}
    J -->|Yes| K[オーバーレイ表示]
    J -->|No| I
    K --> L{修正要求?}
    L -->|Yes| M[修正候補表示]
    L -->|No| I
    M --> N{選択}
    N -->|修正| O[単語置換]
    N -->|辞書追加| P[辞書更新]
    O --> I
    P --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-57-01 | フェイス除外 | コードブロック等の特定フェイスはスキップ | spell-fu使用時 |
| BR-57-02 | Orgブロック除外 | PROPERTIES、SRC、EXAMPLEブロックはスキップ | 常時 |
| BR-57-03 | スペルチェッカー優先 | aspell > hunspell > enchant の順で検索 | フラグ未指定時 |
| BR-57-04 | 重複マーク抑制 | proselintやlangtool使用時は重複マークを無効化 | flyspell使用時 |

### 計算ロジック

- スペルチェッカー検出: `executable-find`で順次チェック
- 辞書パス: `ispell-personal-dictionary`（aspell使用時）

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

本機能はデータベース操作を行わない。ファイルシステム上の辞書を使用する。

### 操作別ファイル影響一覧

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 辞書追加 | `ispell-personal-dictionary` | WRITE | 個人辞書への単語追加 |
| spell-fu辞書 | `spell-fu-directory` | READ/WRITE | spell-fu用辞書データ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | スペルチェッカー未検出 | aspell/hunspell/enchantが未インストール | 警告ログ出力 |
| - | 辞書エラー | 辞書ファイルが破損 | ispell-check-versionで確認 |

### リトライ仕様

リトライ処理は不要。

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

トランザクション処理は不要。

## パフォーマンス要件

- spell-fu: flyspellより高速なリアルタイムチェック
- flyspell-lazy: アイドル時にのみチェック実行（パフォーマンス向上）

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

特になし。

## 備考

- spell-fuはaspellのみをサポート
- flyspell-correct-ivyはIvy統合、flyspell-correct-helmはHelm統合

---

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

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

### 推奨読解順序

#### Step 1: ispell設定を理解する

まず、ispellの基本設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/checkers/spell/config.el` | ispell設定（5-67行目） |

**読解のコツ**: `pcase`でスペルチェッカーを条件分岐。

**主要処理フロー**:
1. **10行目**: `ispell-word`を`+spell/correct`にリマップ
2. **14-17行目**: ispellスキップリージョンの設定
3. **24-63行目**: aspell/hunspell/enchantの検出と設定

#### Step 2: spell-fu設定を理解する（-flyspellフラグ時）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/checkers/spell/config.el` | spell-fu設定（75-151行目） |

**主要処理フロー**:
- **77行目**: aspell必須チェック
- **80-86行目**: 補完UIとの統合設定
- **89-133行目**: `+spell-excluded-faces-alist`定義
- **142-146行目**: フェイス除外処理

#### Step 3: flyspell設定を理解する（デフォルト）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/checkers/spell/config.el` | flyspell設定（153-231行目） |

**主要処理フロー**:
- **160-167行目**: テキストモードでflyspell-modeを有効化
- **169-173行目**: +everywhere時にプログラミングモードでも有効化
- **178-181行目**: welcome/messageフラグの無効化
- **183-190行目**: proselint/langtool検出時の重複マーク抑制

#### Step 4: 修正機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload/+spell-fu.el | `modules/checkers/spell/autoload/+spell-fu.el` | spell-fu用修正（49-111行目） |
| 4-2 | autoload/+flyspell.el | `modules/checkers/spell/autoload/+flyspell.el` | flyspell用修正（31-61行目） |

**主要処理フロー**:
- **+spell/correct**: 修正候補を表示し、選択に応じて処理
- **+spell/add-word**: 個人辞書またはセッション辞書に追加

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

```
text-mode-hook / prog-mode-hook
    │
    ├─ flyspell-mode (+flyspellフラグなし)
    │      │
    │      ├─ flyspell-correct (+spell/correct)
    │      │      │
    │      │      ├─ flyspell-correct-ivy
    │      │      ├─ flyspell-correct-helm
    │      │      └─ flyspell-correct-popup
    │      │
    │      └─ flyspell-lazy-mode
    │
    └─ spell-fu-mode (-flyspellフラグ)
           │
           ├─ +spell/correct
           │      │
           │      ├─ +spell-correct-ivy-fn
           │      ├─ +spell-correct-helm-fn
           │      └─ +spell-correct-generic-fn
           │
           └─ spell-fu-word-add (+spell/add-word)
```

### データフロー図

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

テキスト ───▶ flyspell/spell-fu ───▶ ispell-process
                      │                       │
                      ▼                       ▼
              単語抽出 ───▶ aspell/hunspell ───▶ 判定結果
                      │                       │
                      ▼                       ▼
              オーバーレイ ◀──────── スペルミス検出
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/checkers/spell/config.el` | ソース | メイン設定 |
| packages.el | `modules/checkers/spell/packages.el` | 設定 | 依存パッケージ定義 |
| doctor.el | `modules/checkers/spell/doctor.el` | 診断 | スペルチェッカー確認 |
| autoload/+flyspell.el | `modules/checkers/spell/autoload/+flyspell.el` | ソース | flyspell用コマンド |
| autoload/+spell-fu.el | `modules/checkers/spell/autoload/+spell-fu.el` | ソース | spell-fu用コマンド |
