# 機能設計書 37-ファイルツリーブラウザ（Treemacs）

## 概要

本ドキュメントは、Doom EmacsにおけるTreemacsファイルツリーブラウザ機能の設計を記載する。この機能は、treemacsパッケージを使用して高機能なファイルツリー表示を提供し、プロジェクト管理、Git統合、ワークスペース連携などの機能を備える。

### 本機能の処理概要

**業務上の目的・背景**：大規模プロジェクトの開発において、ファイル構造の把握と効率的なナビゲーションは重要である。Treemacsは、Neotreeよりも高機能なファイルツリービューアを提供し、Git状態の表示、projectile連携、persp-mode連携などを通じて、IDE的な開発体験を実現する。

**機能の利用シーン**：
- プロジェクト全体のファイル構造を確認する場合
- Gitの変更状態を視覚的に確認する場合
- 複数プロジェクトを同時に管理する場合
- LSP連携でシンボル情報を表示する場合
- ワークスペースごとにファイルツリーをスコープする場合

**主要な処理内容**：
1. treemacsパッケージの初期化と設定
2. プロジェクトルートでのファイルツリー表示
3. Gitモードによる変更状態の表示
4. Evil統合によるVim風キーバインド
5. Projectile連携によるプロジェクト認識
6. persp-mode連携によるワークスペーススコープ
7. LSP連携によるシンボル表示

**関連システム・外部連携**：
- treemacsパッケージ
- treemacs-evil（Evil統合）
- treemacs-projectile（Projectile連携）
- treemacs-magit（Magit連携）
- treemacs-persp（persp-mode連携）
- lsp-treemacs（LSP連携）
- treemacs-nerd-icons（アイコン）

**権限による制御**：特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Treemacs | 主機能 | ファイルツリー表示、ディレクトリナビゲーション、Git状態表示 |

## 機能種別

UI表示 / ファイルナビゲーション / プロジェクト管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| +treemacs-git-mode | symbol | No | Git統合モード | 'simple/'extended/'deferred |
| treemacs-follow-after-init | boolean | No | 初期化後にフォロー | t |
| treemacs-sorting | symbol | No | ソート方法 | 'alphabetic-case-insensitive-asc |

### 入力データソース

- ファイルシステム
- Git状態
- プロジェクト情報（projectile）
- ワークスペース情報（persp-mode）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| treemacs-buffer | buffer | Treemacs表示用バッファ |
| ファイルツリー | 表示 | ディレクトリ構造とGit状態の視覚的表示 |

### 出力先

専用のサイドウィンドウ（左側）

## 処理フロー

### 処理シーケンス

```
1. +treemacs/toggle の呼び出し
   └─ ユーザーコマンドによる起動
2. Treemacsの可視性チェック
   └─ treemacs-current-visibility
3. ウィンドウの表示/非表示
   └─ visible: delete-window / invisible: treemacs-add-and-display
4. プロジェクト検出
   └─ treemacs--find-current-user-project
5. Gitモードの設定
   └─ treemacs-git-mode で統合レベル設定
6. 各種統合パッケージの読み込み
   └─ treemacs-evil, treemacs-projectile, etc.
```

### フローチャート

```mermaid
flowchart TD
    A[Treemacs起動] --> B{可視性チェック}
    B -->|visible| C[ウィンドウ削除]
    B -->|invisible| D[プロジェクト検出]
    D --> E{有効なプロジェクト?}
    E -->|Yes| F[treemacs-add-and-display-current-project-exclusively]
    E -->|No| G[treemacs で最後のセッション表示]
    F --> H[Gitモード設定]
    G --> H
    H --> I{Gitモードタイプ}
    I -->|simple| J[ファイルのみハイライト]
    I -->|extended/deferred| K[ファイル+ディレクトリハイライト]
    J --> L[表示完了]
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-37-1 | フォロー無効 | 初期化後のカーソル追従を無効化 | treemacs-follow-mode -1 |
| BR-37-2 | never-other-window | other-windowで選択されないよう設定 | treemacs-is-never-other-window = t |
| BR-37-3 | ソート順 | アルファベット順（大文字小文字区別なし） | treemacs-sorting |
| BR-37-4 | Gitモードフォールバック | python3がない場合はsimpleモードへ | extended/deferredモード時 |
| BR-37-5 | ディレクトリ折りたたみ | extended/deferredモード時は3レベル折りたたみ | treemacs-collapse-dirs |
| BR-37-6 | ポップアップ無視 | Treemacsはポップアップルールを無視 | set-popup-rule! :ignore t |

### 計算ロジック

特になし

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

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

該当なし（データベース操作を行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Python未検出 | python3が見つからない | simpleモードへフォールバック |
| - | プロジェクト検出失敗 | 有効なプロジェクトがない | 最後のセッションを表示 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 大規模プロジェクトでもスムーズに表示できること
- Gitモードでの状態更新が編集操作を妨げないこと
- 非同期処理（deferredモード）での応答性確保

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

特になし

## 備考

- treemacsパッケージのピン留めバージョン: 2ab5a3c89fa01bbbd99de9b8986908b2bc5a7b49
- treemacs-nerd-iconsパッケージのピン留めバージョン: 0c5ddcb978da639f01ddb023febc40fc755171e5
- lsp-treemacsパッケージのピン留めバージョン: 49df7292c521b4bac058985ceeaf006607b497dd

---

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

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

### 推奨読解順序

#### Step 1: パッケージ定義を理解する

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

**読解のコツ**: 条件付きパッケージ（modulep!でのフラグチェック）に注意。

#### Step 2: 設定ファイルを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/treemacs/config.el` | treemacsの設定と統合パッケージ |

**主要処理フロー**:
- **3-14行目**: `+treemacs-git-mode`変数定義
- **20-27行目**: `use-package!`によるtreemacs基本設定
- **29-30行目**: フォローモード無効化
- **32行目**: ポップアップルールの設定（無視）
- **33-43行目**: Gitモード設定とフォールバック処理
- **46-53行目**: treemacs-nerd-icons設定
- **56-70行目**: treemacs-evil設定（Evil統合）
- **73-74行目**: treemacs-projectile設定
- **77-79行目**: treemacs-magit設定
- **82-85行目**: treemacs-persp設定
- **88-90行目**: lsp-treemacs設定

#### Step 3: autoload関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | autoload.el | `modules/ui/treemacs/autoload.el` | カスタムトグルコマンド |

**主要処理フロー**:
- **4-19行目**: `+treemacs/toggle`関数
  - **13行目**: 可視性チェック（treemacs-current-visibility）
  - **14行目**: visible時はウィンドウ削除
  - **15-19行目**: invisible時はプロジェクト表示

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

```
+treemacs/toggle
    │
    ├─ treemacs-current-visibility
    │      │
    │      ├─ `visible → treemacs-get-local-window
    │      │              └─ delete-window
    │      │
    │      └─ `invisible → treemacs--find-current-user-project
    │                        │
    │                        ├─ (有効なプロジェクト)
    │                        │      └─ treemacs-add-and-display-current-project-exclusively
    │                        │
    │                        └─ (無効)
    │                               └─ treemacs
    │
    └─ 統合パッケージ
           ├─ treemacs-evil
           ├─ treemacs-projectile
           ├─ treemacs-magit
           ├─ treemacs-persp
           └─ lsp-treemacs
```

### データフロー図

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

ファイルシステム ───▶ ツリー構築 ───────▶ Treemacs表示
    │                    │
Git状態 ────────────▶ ハイライト処理 ──▶ 変更表示
    │                    │
Projectile ─────────▶ プロジェクト認識 ─▶ ルート設定
    │                    │
persp-mode ─────────▶ スコープ設定 ────▶ ワークスペース連携
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/treemacs/config.el` | ソース | treemacs設定と統合 |
| autoload.el | `modules/ui/treemacs/autoload.el` | ソース | カスタムコマンド定義 |
| packages.el | `modules/ui/treemacs/packages.el` | 設定 | 依存パッケージ定義 |
| doctor.el | `modules/ui/treemacs/doctor.el` | 診断 | 設定診断 |
