# 機能設計書 50-Diredファイルマネージャ強化

## 概要

本ドキュメントは、Doom EmacsにおけるDiredファイルマネージャ強化機能の設計仕様を記述する。dirvishを基盤として、Emacsのファイルマネージャ（Dired）を高機能化し、ファイル操作、プレビュー、ナビゲーションを大幅に改善する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：ファイル操作はソフトウェア開発において日常的なタスクである。Emacsの標準Diredは強力だが、現代的なファイルマネージャと比較すると操作性やビジュアルに改善の余地がある。本機能は、dirvishによる拡張されたUIとナビゲーション機能、diredflによる色付け、dired-xによる省略表示とOS連携を統合し、IDE並みのファイル管理体験を提供する。

**機能の利用シーン**：
- プロジェクト内のファイル閲覧・操作
- ファイルのコピー、移動、削除、リネーム
- rsyncによるリモートファイル同期
- サブツリー表示によるディレクトリ構造の把握
- wdiredによるファイル名の一括編集
- 画像サムネイル表示

**主要な処理内容**：
1. dirvishによる拡張UI（ヘッダー、モードライン、アトリビュート）
2. ディレクトリナビゲーション（h/l, history, subtree）
3. ファイル操作（yank, mark, copy, delete）
4. rsync連携によるファイル転送
5. OS標準アプリによるファイルオープン

**関連システム・外部連携**：
- dirvish: Dired拡張エンジン
- diredfl: ファイル色分け
- dired-x: 拡張機能（省略表示、OS連携）
- dired-aux: 補助機能
- image-dired: 画像サムネイル
- wdired: 編集可能Dired

**権限による制御**：特になし（全ユーザーが利用可能）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面関連なし（ファイルマネージャ機能） |

## 機能種別

ファイル管理 / ナビゲーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| dired-dwim-target | boolean | No | 分割ウィンドウでの自動ターゲット | - |
| dired-recursive-copies | symbol | No | 再帰コピー方法 | 'always, 'top, nil |
| dired-recursive-deletes | symbol | No | 再帰削除方法 | 'always, 'top, nil |
| dired-listing-switches | string | No | ls コマンドのオプション | - |
| dirvish-attributes | list | No | 表示するアトリビュート | シンボルのリスト |

### 入力データソース

- ファイルシステム
- ユーザー設定（init.el/config.el）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ファイルリスト | display | ディレクトリ内容の表示 |
| ファイル操作結果 | file | コピー/移動/削除されたファイル |

### 出力先

- バッファ（Diredバッファ）
- ファイルシステム（操作結果）

## 処理フロー

### 処理シーケンス

```
1. Diredバッファ作成
   ├─ dirvish-dired-noselect-a (advice)
   └─ dirvish-override-dired-mode
2. 表示カスタマイズ
   ├─ dirvish-attributes設定
   ├─ diredfl-mode有効化
   └─ dired-omit-mode有効化
3. ナビゲーション
   ├─ h/l: ディレクトリ移動
   ├─ gh/gl: サブツリー
   └─ M-b/M-f: 履歴
4. ファイル操作
   ├─ y: コピーメニュー
   ├─ s: シンボリックリンク
   └─ p: ヤンク（貼り付け）
5. クリーンアップ
   └─ +dired--cleanup-dirvish-h
```

### フローチャート

```mermaid
flowchart TD
    A[dired起動] --> B[dirvish-override-dired-mode]
    B --> C{+dirvishフラグ?}

    C -->|Yes| D[属性表示有効化]
    C -->|No| E[最小構成]

    D --> F[dirvish-attributes設定]
    E --> F

    F --> G[diredfl-mode]
    G --> H[dired-omit-mode]
    H --> I[キーバインド設定]

    I --> J{操作}
    J -->|h| K[親ディレクトリへ]
    J -->|l| L[ファイル/ディレクトリを開く]
    J -->|TAB| M[サブツリートグル]
    J -->|y| N[コピーメニュー]

    K --> J
    L --> J
    M --> J
    N --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | DWIM ターゲット | 分割ウィンドウ時に他方をターゲットに | dired-dwim-target = t |
| BR-02 | 再帰コピー | サブディレクトリも含めてコピー | dired-recursive-copies = 'always |
| BR-03 | 省略ファイル | ドットファイル、ビルド成果物を非表示 | dired-omit-mode |
| BR-04 | TRAMP対応 | リモートファイルはGNU lsオプション除去 | file-remote-p |
| BR-05 | セッション再利用 | ファイルオープン時のみセッション再利用 | dirvish-reuse-session = 'open |

### 計算ロジック

省略ファイルパターン:
```elisp
(setq dired-omit-files
      (concat dired-omit-files
              "\\|^\\.DS_Store\\'"
              "\\|^flycheck_.*"
              "\\|^\\.project\\(?:ile\\)?\\'"
              "\\|^\\.\\(?:svn\\|git\\)\\'"
              "\\|^\\.ccls-cache\\'"
              "\\|\\(?:\\.js\\)?\\.meta\\'"
              "\\|\\.\\(?:elc\\|o\\|pyo\\|swp\\|class\\)\\'"))
```

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | message | glsが見つからない（BSD） | 標準lsを使用 |
| - | advice | dired-virtual-revertで自動revert防止 | revert処理をスキップ |

### リトライ仕様

リトライ処理は不要。

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

トランザクション処理は不要。ファイル操作は即時反映。

## パフォーマンス要件

- ディレクトリ表示: 即座（ファイル数に比例）
- サムネイル生成: 150pxサイズ
- dirvish再表示: フレーム間フリッカー防止のためデバウンス

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

- ファイル削除は確認なしで実行（dired-recursive-deletes = 'top）
- 隠しファイルは省略表示で非表示

## 備考

- `dirvish-cache-dir`はdoom-cache-dir配下に設定
- `image-dired-dir`はdoom-profile-cache-dir配下に設定
- centaur-tabs使用時はDiredバッファでタブ非表示
- persp/projectile切り替え時にdirvishセッションをクリーンアップ

---

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

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

### 推奨読解順序

#### Step 1: Dired基本設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/emacs/dired/config.el` | Dired基本設定 |

**読解のコツ**:
- **6-69行目**: dired設定（use-package!ブロック）
- **9-24行目**: 基本変数（dwim, recursive, image-dired）
- **30-51行目**: lsオプション設定（BSD対応）
- **62行目**: wdiredキーバインド
- **65-69行目**: doom-escape-hookでのwdired終了

#### Step 2: dirvish設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/emacs/dired/config.el` | dirvish設定 |

**主要処理フロー**:
- **72-190行目**: dirvish設定（use-package!ブロック）
- **76-79行目**: advice設定（diredオーバーライド）
- **104-110行目**: +dirvishフラグ条件分岐
- **141-176行目**: キーバインド設定
- **180-190行目**: persp/projectile連携クリーンアップ

#### Step 3: 補助パッケージを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/emacs/dired/config.el` | diredfl, dired-x |

**主要処理フロー**:
- **193-195行目**: diredfl設定
- **198-230行目**: dired-x設定（省略ファイル、OS連携）
- **233-237行目**: dired-aux設定

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

```
dired-jump / find-file (ディレクトリ)
    │
    ├─ dirvish-dired-noselect-a
    │      └─ dirvish--find-entry
    │
    ├─ dirvish-override-dired-mode
    │      └─ Diredバッファ作成
    │
    ├─ diredfl-mode
    │      └─ ファイル色分け
    │
    └─ dired-omit-mode
           └─ 省略ファイル非表示

dirvish-side (サイドパネル)
    │
    ├─ dirvish-side--session-visible-p
    │
    └─ +dired/dirvish-side-and-follow
           └─ dirvish-side--auto-jump

ファイル操作 (y, s, p等)
    │
    ├─ dirvish-copy-file-*
    │      └─ パスコピー
    │
    ├─ dirvish-symlink / dirvish-hardlink
    │      └─ リンク作成
    │
    └─ dirvish-yank
           └─ ファイルペースト
```

### データフロー図

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

ディレクトリパス       ┌──────────────────────┐
      ───────────────▶│ dirvish-override     │
                      │ dired-mode           │
                      └──────────────────────┘
                               │
                               ▼
                      ┌──────────────────────┐
                      │ ls コマンド実行      │
                      │ (dired-listing-      │
                      │  switches)           │
                      └──────────────────────┘
                               │
                               ▼
                      ┌──────────────────────┐
ファイルリスト ◀───── │ dirvish-attributes   │
表示                   │ 表示整形             │
                      └──────────────────────┘
                               │
                               ▼
                      ┌──────────────────────┐
色分け表示   ◀─────── │ diredfl-mode         │
                      └──────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/emacs/dired/config.el` | ソース | dired/dirvish/diredfl/dired-x設定 |
| autoload.el | `modules/emacs/dired/autoload.el` | ソース | コマンド定義（quit-all, dirvish-side-and-follow） |
| packages.el | `modules/emacs/dired/packages.el` | 設定 | 依存パッケージ（dirvish, diredfl） |
