# 機能設計書 53-Undo履歴の可視化・管理

## 概要

本ドキュメントは、Doom Emacsの`emacs/undo`モジュールが提供するUndo履歴の可視化・管理機能の設計仕様を記述する。undo-fuまたはundo-treeを使用した高度なundo/redo機能と、セッション間での履歴永続化、視覚的なundo履歴ツリー表示を提供する。

### 本機能の処理概要

**業務上の目的・背景**：テキスト編集において、変更の取り消し（undo）とやり直し（redo）は最も頻繁に使用される操作の一つである。Emacs標準のundo機能は直線的な履歴モデルを採用しているが、複雑な編集作業では分岐した履歴を管理したい場合がある。本機能は、より直感的なundo/redo操作と、編集履歴の永続化により、Emacsを閉じた後も履歴を復元できる機能を提供する。

**機能の利用シーン**：
- テキスト編集中の変更取り消し・やり直し
- 過去の編集状態への復帰
- 複数の編集分岐からの選択（undo-tree使用時）
- Emacs再起動後の編集履歴復元

**主要な処理内容**：
1. undo-fuによる線形undo/redo操作
2. undo-fu-sessionによるセッション間履歴永続化
3. vundoによるビジュアルundo履歴表示
4. undo-treeによるツリー状履歴管理（+treeフラグ使用時）
5. zstd圧縮による履歴ファイルサイズ削減

**関連システム・外部連携**：
- undo-fu（線形undo/redo）
- undo-fu-session（履歴永続化）
- vundo（ビジュアル履歴表示）
- undo-tree（ツリー状履歴管理）
- zstd（圧縮ツール）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | vundo/undo-tree visualizer | 主画面 | undo履歴のビジュアル表示、ナビゲーション |
| - | 全エディタバッファ | 主画面 | undo/redo操作の実行 |

## 機能種別

テキスト編集支援 / 履歴管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| +tree | flag | No | undo-treeを使用するかどうか | modulep!でチェック |

### 入力データソース

- `buffer-undo-list`（バッファのundo履歴）
- 永続化された履歴ファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| undo後のバッファ内容 | string | undo操作後のテキスト |
| 履歴ファイル | file | セッション間で保存される履歴データ |

### 出力先

- 現在のエディタバッファ
- `doom-profile-cache-dir/undo-fu-session/`または`doom-profile-cache-dir/undo-tree-hist/`

## 処理フロー

### 処理シーケンス

```
1. バッファ読み込み時
   └─ undo-fu-session-recover または undo-tree履歴読み込み
2. ユーザーが編集操作
   └─ buffer-undo-listに操作を記録
3. undo/redo実行（C-_, M-_等）
   └─ undo-fu-only-undo/redo または undo-tree-undo/redo
4. バッファ保存時
   └─ undo-fu-session-save または undo-tree-save-history
```

### フローチャート

```mermaid
flowchart TD
    A[バッファ読み込み] --> B{履歴ファイル存在?}
    B -->|Yes| C[履歴復元]
    B -->|No| D[新規履歴開始]
    C --> E[編集操作]
    D --> E
    E --> F{undo/redo?}
    F -->|undo| G[undo-fu-only-undo]
    F -->|redo| H[undo-fu-only-redo]
    F -->|No| I{visualize?}
    I -->|Yes| J[vundo/undo-tree-visualize]
    I -->|No| E
    G --> E
    H --> E
    J --> K[履歴選択]
    K --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-53-01 | 履歴制限（undo-fu） | undo-limit: 256KB, undo-strong-limit: 2MB, undo-outer-limit: 36MB | +treeフラグなし |
| BR-53-02 | 履歴制限（undo-tree） | undo-limit: 800KB, undo-strong-limit: 12MB, undo-outer-limit: 128MB | +treeフラグあり |
| BR-53-03 | 永続化除外ファイル | .gpg、COMMIT_EDITMSG、git-rebase-todoは除外 | 常時 |
| BR-53-04 | zstd圧縮 | zstdが利用可能な場合は履歴ファイルを圧縮 | executable-find "zstd" |

### 計算ロジック

- 履歴ファイル名生成: `make-backup-file-name-1`によるSHA1ハッシュ化
- 圧縮: zstd標準圧縮

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

本機能はデータベース操作を行わない。ファイルシステム上に履歴を保存する。

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

| 操作 | 対象ディレクトリ | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 履歴保存 | `undo-fu-session/` | WRITE | セッション履歴の保存 |
| 履歴読み込み | `undo-fu-session/` | READ | セッション履歴の復元 |
| 履歴保存（tree） | `undo-tree-hist/` | WRITE | ツリー履歴の保存 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 履歴破損 | 履歴ファイルが破損 | 新規履歴として開始 |
| - | パッケージ競合 | undo-fuとundo-treeの同時使用 | doctor.elで警告表示 |

### リトライ仕様

リトライ処理は不要。

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

- 履歴保存は非同期で行われる
- 保存失敗時はサイレントに処理（ユーザー操作を阻害しない）

## パフォーマンス要件

- undo/redo操作: 即時（体感遅延なし）
- 履歴ファイル読み込み: 数MB程度でも100ms以内（zstd使用時）

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

- GPG暗号化ファイル（.gpg）の履歴は保存しない
- 認証情報を含む可能性のあるファイルの履歴は保存対象外

## 備考

- Emacs 27以下ではvundoは使用不可
- テキストプロパティは履歴から除去（パフォーマンス向上のため）

---

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

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

### 推奨読解順序

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

まず、undo制限値とディレクトリ設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/emacs/undo/config.el` | undo-fuセクション（3-24行目） |
| 1-2 | config.el | `modules/emacs/undo/config.el` | undo-treeセクション（61-125行目） |

**読解のコツ**: `modulep! +tree`で分岐し、undo-fuかundo-treeのどちらかのみが有効化される。

#### Step 2: undo-fuの設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/emacs/undo/config.el` | `use-package! undo-fu`（3-24行目） |

**主要処理フロー**:
1. **5行目**: `doom-first-buffer`フックで`undo-fu-mode`を有効化
2. **8-10行目**: undo制限値の設定（256KB, 2MB, 36MB）
3. **12-23行目**: `undo-fu-mode`マイナーモードの定義とキーマップ

#### Step 3: セッション永続化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/emacs/undo/config.el` | `use-package! undo-fu-session`（27-48行目） |

**主要処理フロー**:
- **29行目**: `undo-fu-mode`フックで`global-undo-fu-session-mode`を有効化
- **30行目**: 保存ディレクトリの設定
- **32行目**: 除外ファイルパターンの設定
- **34-37行目**: zstd圧縮の有効化
- **44-48行目**: ファイル名のSHA1ハッシュ化（長いパス対策）

#### Step 4: vundo（ビジュアル履歴）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/emacs/undo/config.el` | `use-package! vundo`（51-58行目） |

**主要処理フロー**:
- **53行目**: Emacs 28以上でのみ有効
- **56-57行目**: Unicode記号使用、コンパクト表示設定

#### Step 5: undo-tree（代替実装）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | config.el | `modules/emacs/undo/config.el` | `use-package! undo-tree`（61-125行目） |

**主要処理フロー**:
- **64行目**: `global-undo-tree-mode`の有効化
- **67-77行目**: undo-tree固有の設定（visualizer-diff、auto-save等）
- **85-88行目**: zstd圧縮の有効化
- **93-98行目**: テキストプロパティの除去（パフォーマンス対策）

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

```
undo-fu-mode (有効化)
    │
    ├─ undo-fu-only-undo (C-_)
    │
    ├─ undo-fu-only-redo (M-_)
    │
    └─ undo-fu-session
           │
           ├─ undo-fu-session-save (自動)
           │      └─ zstd圧縮 (オプション)
           │
           └─ undo-fu-session-recover (バッファ読み込み時)
                  └─ zstd解凍 (オプション)

vundo (M-x vundo)
    │
    └─ vundo-quit (終了)

undo-tree-mode (+tree有効時)
    │
    ├─ undo-tree-undo
    │
    ├─ undo-tree-redo
    │
    └─ undo-tree-visualize
           │
           └─ undo-tree-visualizer-show-diff
```

### データフロー図

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

編集操作 ───▶ buffer-undo-list ───▶ undo履歴
                      │
                      ▼
              undo/redo実行
                      │
                      ▼
              バッファ状態変更
                      │
                      ▼
              undo-fu-session-save
                      │
                      ▼
              履歴ファイル (.zst)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/emacs/undo/config.el` | ソース | メイン設定、パッケージ設定 |
| packages.el | `modules/emacs/undo/packages.el` | 設定 | 依存パッケージ定義 |
| doctor.el | `modules/emacs/undo/doctor.el` | 診断 | undo-fu/undo-tree競合チェック |
