# 機能設計書 29-インデントガイド表示

## 概要

本ドキュメントは、Doom Emacsにおけるインデントガイド表示機能の設計を記述する。indent-barsパッケージを使用し、コードのインデントレベルを視覚的なガイドライン（縦線）として表示することで、コード構造の把握を容易にする。

### 本機能の処理概要

**業務上の目的・背景**：Pythonなどインデントが重要な言語や、深いネストを持つコードにおいて、インデントレベルを視覚的に把握することは重要である。インデントガイドを表示することで、コードブロックの範囲を直感的に理解でき、コーディングやコードレビューの効率が向上する。

**機能の利用シーン**：プログラミング時のコード構造把握、深いネストの可視化、Pythonなどインデント重視言語での編集、コードレビュー時の構造確認。

**主要な処理内容**：
1. after-change-major-mode-hookでのindent-bars-mode条件付き有効化
2. インデントレベルに応じたガイドライン描画
3. ビットマップまたは文字ベースのガイドライン表示
4. 特殊バッファでの無効化（抑制フック）
5. tree-sitter統合による高精度インデント検出

**関連システム・外部連携**：indent-barsパッケージ、tree-sitter（オプション）、lsp-ui-peekとの互換性処理。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | Indent Guides | 主機能 | インデントレベルの視覚的表示 |

## 機能種別

UI表示 / コード構造可視化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| indent-bars-treesit-support | boolean | No | tree-sitterサポートの有効化 | :tools tree-sitterモジュールに依存 |
| indent-bars-prefer-character | boolean | No | 文字ベースガイドの優先使用 | macOS/pgtk環境で自動設定 |
| indent-bars-starting-column | integer | No | ガイド開始カラム（デフォルト: 0） | 0以上の整数 |
| indent-bars-width-frac | float | No | ビットマップ幅の割合（デフォルト: 0.15） | 0-1の小数 |
| indent-bars-color-by-depth | boolean | No | 深度による色分け（デフォルト: nil） | boolean |
| indent-bars-highlight-current-depth | boolean | No | 現在深度のハイライト（デフォルト: nil） | boolean |

### 入力データソース

- バッファ内のテキストとインデント情報
- モジュールフラグ（:tools tree-sitter）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| インデントガイド | overlay/text-property | インデントレベルを示す縦線 |

### 出力先

- バッファ内のテキスト表示

## 処理フロー

### 処理シーケンス

```
1. doom-first-buffer-hookの実行
   └─ +indent-guides-startup-h関数呼び出し
2. after-change-major-mode-hookの登録
   └─ +indent-guides-init-maybe-h関数登録
3. メジャーモード変更時
   └─ 抑制フックのチェック
   └─ 条件を満たす場合、indent-bars-mode有効化
4. インデントガイド描画
   └─ ビットマップまたは文字での縦線表示
```

### フローチャート

```mermaid
flowchart TD
    A[doom-first-buffer-hook] --> B[+indent-guides-startup-h]
    B --> C[after-change-major-mode-hook登録]
    C --> D[メジャーモード変更]
    D --> E{fundamental-mode?}
    E -->|Yes| F[スキップ]
    E -->|No| G{抑制フック実行}
    G -->|抑制| F
    G -->|許可| H[indent-bars-mode有効化]
    H --> I[インデントガイド描画]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-29-01 | fundamental-mode除外 | fundamental-modeではindent-bars-modeを有効化しない | major-mode = fundamental-mode |
| BR-29-02 | 特殊バッファ除外 | doom-special-buffer-pまたはdoom-temp-buffer-pで真のバッファでは無効化 | 抑制フック |
| BR-29-03 | org-indent-mode除外 | org-indent-mode有効時は無効化（仮想インデントと干渉） | org-indent-mode |
| BR-29-04 | einノートブック除外 | ein:notebook-modeかつインライン画像有効時は無効化 | ein:output-area-inlined-images |
| BR-29-05 | childframe除外 | 親フレームを持つchildframeでは無効化 | frame-parameter parent-frame |
| BR-29-06 | macOS文字優先 | macOSではビットマップよりも文字ベースガイドを優先 | featurep :system 'macos |
| BR-29-07 | pgtk文字優先 | Emacs 30未満のpgtkビルドでは文字ベースガイドを優先 | pgtk + emacs < 30 |

### 計算ロジック

特になし

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

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

## エラー処理

### エラーケース一覧

エラーケースは特になし（抑制フックで問題のある状況を回避）

### リトライ仕様

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

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

該当なし

## パフォーマンス要件

- macOSではビットマップ描画が遅いため、文字ベースガイドを優先
- indent-bars-highlight-current-depthをnilに設定し、不要なオーバーヘッドを回避
- indent-bars-color-by-depthをnilに設定し、シンプルな表示を維持

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

- 表示機能のみであり、セキュリティリスクなし

## 備考

- magit-blameと互換性のため、magit-blame-disable-modesに登録
- lsp-ui-peekとの互換性のため、アドバイスで一時的に無効化

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/indent-guides/config.el` | indent-barsパッケージの設定 |
| 1-2 | packages.el | `modules/ui/indent-guides/packages.el` | パッケージ依存定義 |

**読解のコツ**: `+indent-guides-inhibit-functions`フックが抑制条件を定義している。`defun`で定義された各抑制関数の条件を確認する。

**主要処理フロー**:
- **3-9行目**: `+indent-guides-inhibit-functions`カスタム変数定義
- **15-17行目**: `use-package! indent-bars` - パッケージ設定開始
- **19-21行目**: `+indent-guides-startup-h` - スタートアップ関数
- **23-27行目**: `+indent-guides-init-maybe-h` - 条件付き有効化関数
- **30-50行目**: 各種設定（treesit、文字優先、幅、色）
- **57-75行目**: 抑制関数の定義（特殊バッファ、org-indent、ein、childframe）
- **83-92行目**: move-to-columnのアドバイス（blank-lines表示との互換性）
- **97-117行目**: magit-blame、lsp-ui-peekとの互換性処理

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

```
doom-first-buffer-hook
    │
    └─ +indent-guides-startup-h
           │
           └─ after-change-major-mode-hook登録
                  │
                  └─ +indent-guides-init-maybe-h
                         │
                         ├─ +indent-guides-inhibit-functions (抑制チェック)
                         │      ├─ +indent-guides-in-special-buffers-p
                         │      ├─ +indent-guides-in-org-indent-mode-p
                         │      ├─ +indent-guides-in-ein-notebook-p
                         │      └─ +indent-guides-in-childframe-p
                         │
                         └─ indent-bars-mode (有効化)
```

### データフロー図

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

メジャーモード変更 ───▶ +indent-guides-init-maybe-h
                              │
                              ▼
                     抑制フックチェック
                              │
                     ┌────────┴────────┐
                     │                 │
                     ▼                 ▼
              [抑制]スキップ    [許可]indent-bars-mode
                                       │
バッファテキスト ──────────────────────▶ インデント検出
                                       │
                                       ▼
                                ガイドライン描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/indent-guides/config.el` | ソース | メイン設定ファイル |
| packages.el | `modules/ui/indent-guides/packages.el` | 設定 | パッケージ依存定義 |
