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

## 概要

本ドキュメントは、Doom EmacsにおけるNeotreeファイルツリーブラウザ機能の設計を記載する。この機能は、neotreeパッケージを使用してシンプルなファイルツリー表示を提供し、プロジェクト内のファイルナビゲーションを支援する。

### 本機能の処理概要

**業務上の目的・背景**：プロジェクト開発において、ファイル構造を視覚的に把握しながらナビゲーションすることは重要である。Neotreeは軽量でシンプルなファイルツリービューアを提供し、IDE的なファイル操作体験を実現する。プロジェクトルートを自動検出し、関連ファイルへの素早いアクセスを可能にする。

**機能の利用シーン**：
- プロジェクト内のファイル構造を確認する場合
- ディレクトリ間をナビゲーションする場合
- 新規ファイル・ディレクトリを作成する場合
- ファイルを分割ウィンドウで開く場合

**主要な処理内容**：
1. neotreeパッケージの初期化と設定
2. プロジェクトルートでのファイルツリー表示
3. ディレクトリの展開/折りたたみ
4. ファイルのオープン（通常/分割）
5. Evil統合によるVim風キーバインド
6. 隠しファイル・ディレクトリのフィルタリング

**関連システム・外部連携**：
- neotreeパッケージ
- doom-project-root（プロジェクト検出）
- Evilモード

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | Neotree | 主機能 | シンプルなファイルツリー表示、ナビゲーション |

## 機能種別

UI表示 / ファイルナビゲーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| neo-window-width | integer | No | Neotreeウィンドウの幅 | デフォルト30 |
| neo-theme | symbol | No | アイコンテーマ | 'nerd |
| neo-show-hidden-files | boolean | No | 隠しファイル表示 | t or nil |

### 入力データソース

- ファイルシステム
- プロジェクト情報（doom-project-root）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| neo-global--buffer | buffer | Neotree表示用バッファ |
| ファイルツリー | 表示 | ディレクトリ構造の視覚的表示 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. +neotree/open または neotree-toggle の呼び出し
   └─ ユーザーコマンドによる起動
2. プロジェクトルートの検出
   └─ doom-project-root による検出
3. Neotreeウィンドウの表示
   └─ neotree-dir によるディレクトリ表示
4. カーソル位置の調整
   └─ 行頭から最初の非空白文字へ移動
5. ユーザー操作の待機
   └─ キーバインドによるナビゲーション
```

### フローチャート

```mermaid
flowchart TD
    A[Neotree起動] --> B{ウィンドウ存在?}
    B -->|Yes| C[neotree-hide]
    B -->|No| D[プロジェクトルート検出]
    D --> E{ルート検出成功?}
    E -->|Yes| F[neotree-dir でルート表示]
    E -->|No| G[default-directory を使用]
    F --> H[ウィンドウ表示]
    G --> H
    H --> I{ファイル操作?}
    I -->|展開/折りたたみ| J[ディレクトリ状態変更]
    I -->|ファイルオープン| K[バッファでファイル表示]
    I -->|分割オープン| L[新ウィンドウでファイル表示]
    J --> I
    K --> I
    L --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-34-1 | ウィンドウ幅 | デフォルト幅は30文字 | neo-window-width = 30 |
| BR-34-2 | テーマ | nerdアイコンを使用 | neo-theme = 'nerd |
| BR-34-3 | モードライン | Neotreeウィンドウにはモードライン非表示 | neo-mode-line-type = 'none |
| BR-34-4 | バナー非表示 | バナーメッセージを表示しない | neo-banner-message = nil |
| BR-34-5 | 作成確認 | ファイル/ディレクトリ作成時の確認をスキップ | neo-confirm-create-file/directory = #'off-p |
| BR-34-6 | 隠しファイル正規表現 | .git、.hg、.svn等を隠す | neo-hidden-regexp-list |
| BR-34-7 | キースタイル | 簡潔なキーマップスタイル | neo-keymap-style = 'concise |

### 計算ロジック

特になし

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ルート検出失敗 | プロジェクトルートが検出できない | default-directory を使用 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 大規模ディレクトリ構造でもスムーズに表示できること
- ファイル操作がメインバッファの編集を妨げないこと

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

特になし

## 備考

- neotreeパッケージのピン留めバージョン: 3178805a0942696d1e5162575d9cab43d14b7970
- popup-rule で Neotree は無視設定（自前でウィンドウ管理）

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: `:pin`でコミットハッシュが固定されている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/neotree/config.el` | neotreeの設定とキーバインド |

**主要処理フロー**:
- **3-10行目**: `use-package!`によるneotree設定、コマンド定義
- **12-24行目**: 初期設定値（幅、テーマ、表示オプション等）
- **25-36行目**: `neo-hidden-regexp-list`による隠しファイルパターン
- **38-39行目**: ポップアップルールの設定（無視）
- **41-42行目**: winner-boring-buffersへの追加
- **44-55行目**: カーソル位置調整のフック・アドバイス
- **57-73行目**: Evil統合キーマップ定義

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

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

**主要処理フロー**:
- **8-15行目**: `+neotree/open`関数
  - **12-13行目**: ウィンドウ存在チェックとトグル
  - **14-15行目**: doom-project-rootまたはdefault-directoryで表示
- **18-35行目**: `+neotree/find-this-file`関数
  - **21-23行目**: パスとプロジェクトルートの取得
  - **25-35行目**: 条件分岐によるneotree更新処理
- **38-45行目**: `+neotree/collapse-or-up`関数
  - 展開ディレクトリは折りたたみ、そうでなければ親へ移動
- **48-56行目**: `+neotree/collapse`関数
- **59-70行目**: `+neotree/expand-or-open`関数
  - ディレクトリは展開、ファイルはneotree-enterで開く

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

```
ユーザーコマンド
    │
    ├─ +neotree/open
    │      ├─ neo-global--window-exists-p
    │      │      └─ neotree-hide
    │      └─ neotree-dir
    │             └─ doom-project-root
    │
    ├─ +neotree/find-this-file
    │      ├─ neotree-find
    │      └─ neotree-refresh
    │
    ├─ +neotree/collapse-or-up
    │      ├─ +neotree/collapse
    │      └─ neotree-select-up-node
    │
    └─ +neotree/expand-or-open
           ├─ neo-buffer--set-expand
           └─ neotree-enter
```

### データフロー図

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

ユーザー操作 ───▶ コマンド処理 ───▶ Neotreeウィンドウ更新
    │                    │
ファイルシステム ─▶ ディレクトリ読み込み ─▶ ツリー表示
    │                    │
プロジェクト情報 ─▶ ルート検出 ───────▶ ルートパス設定
```

### 関連ファイル一覧

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