# 画面設計書 2-Treemacs

## 概要

本ドキュメントは、Doom Emacsのファイルツリーブラウザ画面（Treemacs）の設計仕様を定義する。

### 本画面の処理概要

Treemacsは、プロジェクトのファイルツリーをサイドパネルとして表示する機能を提供し、ファイル・ディレクトリのナビゲーション、Git統合による変更状態の可視化をサポートする。

**業務上の目的・背景**：
Treemacsは、プロジェクト内のファイル構造を視覚的に把握し、効率的なファイルナビゲーションを実現することを目的としている。IDEライクなサイドバー型ファイルエクスプローラとして機能し、Git状態表示やprojectile/persp-mode連携により、プロジェクトベースの開発ワークフローを強力にサポートする。

**画面へのアクセス方法**：
- `SPC o p` キーバインド（+treemacs/toggle）
- `treemacs` コマンドを直接実行
- `treemacs-select-window` でTreemacsウィンドウを選択

**主要な操作・処理内容**：
1. プロジェクトのファイルツリー表示
2. ディレクトリの展開・折りたたみ
3. ファイルの選択・オープン（通常、水平分割、垂直分割）
4. Git状態（変更、追加、削除等）の色分け表示
5. ファイル・ディレクトリの作成、削除、リネーム
6. プロジェクト間の切り替え

**画面遷移**：
- 遷移元：編集バッファからトグルコマンドで表示
- 遷移先：選択したファイルの編集バッファ

**権限による表示制御**：
- 権限による表示制御は存在しない
- ファイルシステムのパーミッションに従った操作制限のみ

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 37 | ファイルツリーブラウザ（Treemacs） | 主機能 | ファイルツリー表示、ディレクトリナビゲーション、Git状態表示 |
| 7 | プロジェクト管理 | 補助機能 | projectile連携によるプロジェクト認識 |
| 65 | Gitクライアント統合 | 補助機能 | treemacs-magit連携、Git差分表示 |
| 41 | ワークスペース管理（タブ風） | 補助機能 | persp-mode連携によるワークスペーススコープ |
| 43 | Vim エミュレーション | 補助機能 | treemacs-evil連携、Vim風キーバインド |

## 画面種別

サイドパネル型ファイルエクスプローラ

## URL/ルーティング

Emacsアプリケーションのため、URLルーティングは存在しない。バッファ名は`*Treemacs-<scope>*`形式。

## 入出力項目

| 項目名 | 種別 | 必須 | 説明 |
|--------|------|------|------|
| プロジェクトルート | 入力 | いいえ | 表示するプロジェクトのルートディレクトリ（省略時はdoom-project-root） |

## 表示項目

| 項目名 | 種別 | 説明 |
|--------|------|------|
| プロジェクト名 | テキスト | プロジェクトルートディレクトリ名 |
| ディレクトリ | アイコン+テキスト | 展開可能なフォルダ表示 |
| ファイル | アイコン+テキスト | ファイルタイプ別アイコン付きファイル名 |
| Git状態マーカー | 色/アイコン | 変更(M)、追加(A)、未追跡(?)等の状態表示 |

## イベント仕様

### 1-ファイル/ディレクトリ選択

| キー | 動作 |
|------|------|
| RET | ファイルを開く/ディレクトリを展開・折りたたみ |
| TAB | ディレクトリを展開・折りたたみ（treemacs-TAB-action） |
| o v | ファイルを水平分割で開く |
| o s | ファイルを垂直分割で開く |

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

| キー | 動作 |
|------|------|
| j/n | 次のノードへ移動 |
| k/p | 前のノードへ移動 |
| h | 親ノードへ移動 |
| l | 子ノードへ移動/展開 |
| H | 上の兄弟ノードへ移動 |
| L | 下の兄弟ノードへ移動 |

### 3-ファイル操作

| キー | 動作 |
|------|------|
| cf | 新規ファイル作成 |
| cd | 新規ディレクトリ作成 |
| R | リネーム |
| d | 削除 |
| m | 移動 |
| y | コピー |

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

本画面はファイルシステム操作のためのUIであり、データベースとの連携は存在しない。

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

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

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容 |
|---------------|---------|---------------|
| 情報 | プロジェクト未検出時 | "No valid project in current buffer; opening last treemacs session" |
| エラー | ファイル操作失敗時 | Emacsの標準エラーメッセージ |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| プロジェクトルートが検出できない | 最後のTreemacsセッションを開く |
| pythonが見つからない（extended/deferredモード） | simpleモードにフォールバック |
| ファイル操作権限エラー | Emacsの標準エラーハンドリング |

## 備考

- Git統合には3つのモード（simple, extended, deferred）があり、パフォーマンスと機能のトレードオフがある
- treemacs-nerd-iconsを使用してファイルタイプ別のアイコンを表示
- persp-mode有効時はワークスペーススコープでTreemacsが管理される

---

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

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

### 推奨読解順序

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

Treemacsの設定変数とGitモードの設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/treemacs/config.el` | 行3-14: +treemacs-git-mode変数定義 |

**読解のコツ**: `+treemacs-git-mode`はsimple/extended/deferredの3値を取り、Git統合の動作モードを制御する。

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

use-package!マクロによるtreemacsの設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/treemacs/config.el` | 行20-43: treemacsパッケージ設定 |

**主要処理フロー**:
1. **行23-27**: 基本設定（follow-mode, sorting, persist-file等）
2. **行30**: treemacs-follow-modeを無効化
3. **行32**: ポップアップルールで無視設定
4. **行33-43**: Gitモードの設定とフォールバック処理

#### Step 3: 拡張パッケージを理解する

Treemacsと連携する各種拡張パッケージを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/treemacs/config.el` | 行46-53: treemacs-nerd-icons設定 |
| 3-2 | config.el | `modules/ui/treemacs/config.el` | 行56-70: treemacs-evil設定 |
| 3-3 | config.el | `modules/ui/treemacs/config.el` | 行82-85: treemacs-persp設定 |

**主要処理フロー**:
- **行46-53**: nerd-iconsテーマのロードと適用
- **行56-70**: Evil対応キーマップの設定（o v/o sでの分割オープン等）
- **行82-85**: persp-mode有効時にPerspectivesスコープを設定

#### Step 4: インタラクティブコマンドを理解する

Doomが提供するラッパーコマンドを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload.el | `modules/ui/treemacs/autoload.el` | 行4-19: +treemacs/toggle関数 |

**主要処理フロー**:
- **行4-19**: 現在のプロジェクトのみ表示するトグル関数

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

```
+treemacs/toggle
    │
    ├─ treemacs-current-visibility
    │      └─ `visible → delete-window
    │
    └─ treemacs--find-current-user-project
           │
           ├─ プロジェクト有効時
           │      └─ treemacs-add-and-display-current-project-exclusively
           │
           └─ プロジェクト無効時
                  └─ treemacs（デフォルト動作）
```

### データフロー図

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

SPC o p ────────────▶ +treemacs/toggle ───────▶ サイドパネル表示/非表示

プロジェクト選択 ────▶ treemacs-projectile ───▶ プロジェクトツリー更新

Git変更 ────────────▶ treemacs-git-mode ──────▶ ファイル状態色分け
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/treemacs/config.el` | ソース | メイン設定 |
| autoload.el | `modules/ui/treemacs/autoload.el` | ソース | インタラクティブコマンド |
| treemacs | 外部パッケージ | 依存 | ファイルツリー機能本体 |
| treemacs-evil | 外部パッケージ | 依存 | Evilキーバインド統合 |
| treemacs-projectile | 外部パッケージ | 依存 | Projectile統合 |
| treemacs-magit | 外部パッケージ | 依存 | Magit統合 |
| treemacs-persp | 外部パッケージ | 依存 | persp-mode統合 |
| treemacs-nerd-icons | 外部パッケージ | 依存 | アイコン表示 |
