# 機能設計書 52-IBbufferバッファ管理強化

## 概要

本ドキュメントは、Doom Emacsの`emacs/ibuffer`モジュールが提供するIBbufferバッファ管理強化機能の設計仕様を記述する。Emacsの組み込みバッファマネージャであるibufferに対して、プロジェクト別グループ化、アイコン表示、ワークスペース統合などの拡張機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：開発作業中は多数のバッファが開かれることが多く、これらを効率的に管理することは生産性に直結する。標準のibufferでは、バッファがフラットに一覧表示されるため、関連するファイルの把握や操作が困難になることがある。本機能は、プロジェクト単位でのグループ化やアイコン表示により、バッファの視認性と操作性を大幅に向上させる。

**機能の利用シーン**：
- 多数のバッファを開いた状態でのバッファ切り替え
- プロジェクト別にバッファを確認・整理
- ワークスペースごとのバッファ管理
- バッファの一括操作（削除、保存等）

**主要な処理内容**：
1. ibuffer-projectileによるプロジェクト単位でのバッファグループ化
2. nerd-iconsによるファイルタイプアイコンの表示
3. ワークスペース（persp-mode）との統合
4. human-readableなファイルサイズ表示
5. Ivy/Counselとの連携によるファイル検索

**関連システム・外部連携**：
- ibuffer-projectile（プロジェクトベースのフィルタリング）
- ibuffer-vc（バージョン管理ステータス表示）
- nerd-icons（アイコン表示）
- persp-mode（ワークスペース管理）
- Ivy/Counsel（補完フレームワーク）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | IBbufferリスト画面 | 主画面 | バッファ一覧表示、プロジェクト別グループ化 |

## 機能種別

バッファ管理 / UI拡張

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| workspace-name | string | No | フィルタ対象のワークスペース名 | 有効なワークスペース名 |
| select-first | boolean | No | 最初のワークスペースを自動選択 | t/nil |

### 入力データソース

- バッファリスト（`buffer-list`）
- プロジェクトルート（`projectile-project-root`）
- ワークスペースリスト（`+workspace-list`）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| バッファリスト | list | グループ化されたバッファ一覧 |
| アイコン | string | ファイルタイプに応じたnerd-iconアイコン |
| サイズ | string | human-readable形式のファイルサイズ |
| VC状態 | string | バージョン管理ステータス |

### 出力先

- `*Ibuffer*`バッファ

## 処理フロー

### 処理シーケンス

```
1. ibufferを起動（M-x ibuffer または C-x C-b）
   └─ ibuffer-hook が実行される
2. ibuffer-projectile-set-filter-groups が呼び出される
   └─ プロジェクト単位でバッファをグループ化
3. 各バッファのフォーマット処理
   └─ アイコン、サイズ、VCステータスを含むカラムを生成
4. フィルタグループの表示
   └─ 空のグループは非表示（ibuffer-show-empty-filter-groups nil）
```

### フローチャート

```mermaid
flowchart TD
    A[ibuffer起動] --> B[ibuffer-hook実行]
    B --> C[ibuffer-projectile-set-filter-groups]
    C --> D{+icons有効?}
    D -->|Yes| E[nerd-iconsでアイコン生成]
    D -->|No| F[テキストプレフィックス]
    E --> G[バッファリスト表示]
    F --> G
    G --> H{ワークスペース統合?}
    H -->|Yes| I[ワークスペースフィルタ適用]
    H -->|No| J[通常表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-52-01 | 空グループ非表示 | バッファのないプロジェクトグループは非表示 | 常時 |
| BR-52-02 | サイズ表示形式 | ファイルサイズはhuman-readable形式で表示 | 常時 |
| BR-52-03 | アイコン表示 | +iconsフラグ有効時にアイコンを表示 | modulep! +icons |
| BR-52-04 | ワークスペースフィルタ | 特定ワークスペースのバッファのみ表示可能 | :ui workspaces有効時 |

### 計算ロジック

- ファイルサイズ: `file-size-human-readable (buffer-size)`
- アイコン取得: `nerd-icons-icon-for-file` または `nerd-icons-icon-for-mode`

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | バッファ無効 | 存在しないバッファを参照 | `buffer-live-p`でチェック |
| - | ワークスペース無効 | 無効なワークスペース名を指定 | user-errorを発生 |

### リトライ仕様

リトライ処理は不要。

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

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

## パフォーマンス要件

- バッファリスト生成: 数百バッファでも1秒以内
- アイコン表示: 非同期処理でUIブロックを回避

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

特になし。

## 備考

- ibuffer-vcパッケージによりVCステータスも表示可能
- ポップアップルールは`set-popup-rule!`で`:ignore t`に設定（通常ウィンドウで表示）

---

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

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

### 推奨読解順序

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

ibufferの表示フォーマットとカラム定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/emacs/ibuffer/config.el` | `ibuffer-formats`変数（8-23行目） |

**読解のコツ**: `ibuffer-formats`はカラム定義のリスト。各要素がカラムを表し、幅や整列方向を指定できる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/emacs/ibuffer/config.el` | `after! ibuffer`ブロック（3-66行目） |

**主要処理フロー**:
1. **4行目**: ポップアップルールを`:ignore t`に設定
2. **6-7行目**: 空グループ非表示、グループ名フェイス設定
3. **26-33行目**: アイコンカラムの定義
4. **36-40行目**: サイズカラムの再定義（human-readable）

#### Step 3: ワークスペース統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | autoload/workspaces.el | `modules/emacs/ibuffer/autoload/workspaces.el` | ワークスペース関連関数（5-34行目） |

**主要処理フロー**:
- **5-8行目**: `+ibuffer-workspace`でワークスペース用ibufferを開く
- **11-14行目**: `+ibuffer/open-for-current-workspace`で現在のワークスペース用
- **17-34行目**: `+ibuffer/visit-workspace-buffer`でバッファのワークスペースに切り替え

#### Step 4: プロジェクト統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/emacs/ibuffer/config.el` | `use-package! ibuffer-projectile`（69-80行目） |

**主要処理フロー**:
- **71行目**: ibufferフックで`ibuffer-projectile-set-filter-groups`を呼び出し
- **73-80行目**: プレフィックスにアイコンまたは"Project: "を設定

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

```
ibuffer (起動)
    │
    ├─ ibuffer-hook
    │      └─ ibuffer-projectile-set-filter-groups
    │
    ├─ ibuffer-formats (カラム定義)
    │      ├─ icon (define-ibuffer-column)
    │      │      └─ nerd-icons-icon-for-file
    │      │      └─ nerd-icons-icon-for-mode
    │      │
    │      └─ size (define-ibuffer-column)
    │             └─ file-size-human-readable
    │
    └─ workspace-buffers (define-ibuffer-filter)
           └─ +workspace-buffer-list
```

### データフロー図

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

buffer-list ───▶ ibuffer-projectile ───▶ グループ化バッファ
                      │
                      ▼
              define-ibuffer-column
                      │
           ┌──────────┼──────────┐
           ▼          ▼          ▼
        icon        size      vc-status
           │          │          │
           └──────────┴──────────┘
                      │
                      ▼
              *Ibuffer*バッファ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/emacs/ibuffer/config.el` | ソース | メイン設定、カラム定義 |
| packages.el | `modules/emacs/ibuffer/packages.el` | 設定 | 依存パッケージ定義 |
| autoload/workspaces.el | `modules/emacs/ibuffer/autoload/workspaces.el` | ソース | ワークスペース統合機能 |
