# 機能設計書 7-プロジェクト管理

## 概要

本ドキュメントは、Doom Emacsのプロジェクト管理システム（doom-projects.el）の機能設計を記述する。このシステムは、projectileパッケージを基盤としたプロジェクト検出・ナビゲーション機能と、プロジェクト固有のマイナーモード定義機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：現代のソフトウェア開発は、複数のプロジェクトを横断して作業することが一般的である。プロジェクト管理システムは、プロジェクトルートの自動検出、プロジェクト内ファイル検索、プロジェクト固有設定などを提供し、開発者の生産性を向上させる。

**機能の利用シーン**：
- プロジェクト内ファイルの高速検索
- プロジェクト間の切り替え
- プロジェクト固有の設定・フックの適用
- バージョン管理システムとの連携

**主要な処理内容**：
1. プロジェクトルート検出（projectile、project.el）
2. ファイルインデックス作成（fd、ripgrep使用）
3. プロジェクト固有マイナーモード定義（def-project-mode!）
4. プロジェクトキャッシュ管理
5. 既知プロジェクト一覧管理

**関連システム・外部連携**：projectile、project.el、fd（fdfind）、ripgrep

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | プロジェクト操作全般に関連 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| doom-fd-executable | string | No | fdコマンドのパス | executable-find |
| doom-ripgrep-executable | string | No | rgコマンドのパス | executable-find |
| doom-project-cache-dir | string | No | キャッシュディレクトリ | ディレクトリ |

### 入力データソース

- ファイルシステム（.git、.project等のマーカー）
- 環境変数（PATH）
- projectile設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| projectile-known-projects | list | 既知プロジェクト一覧 |
| project-list-file | file | project.elの既知プロジェクト |
| キャッシュファイル | file | プロジェクトファイルインデックス |

### 出力先

- キャッシュディレクトリ（doom-project-cache-dir）
- 状態ディレクトリ（doom-profile-state-dir）

## 処理フロー

### プロジェクトルート検出

```
1. projectile-root-local: projectile-project-root変数を確認
2. projectile-root-bottom-up: /からカレントへ向かって検索
   └─ .git, .project等を検索
3. projectile-root-top-down: カレントから/へ向かって検索
   └─ package.json, setup.py, Cargo.toml等を検索
4. projectile-root-top-down-recurring: 再帰的なマーカーを検索
   └─ Makefile等
```

### フローチャート

```mermaid
flowchart TD
    A[ファイルオープン] --> B{projectile-project-root設定?}
    B -->|Yes| C[そのルートを使用]
    B -->|No| D[projectile-root-bottom-up]
    D --> E{.git/.project発見?}
    E -->|Yes| C
    E -->|No| F[projectile-root-top-down]
    F --> G{package.json等発見?}
    G -->|Yes| C
    G -->|No| H[projectile-root-top-down-recurring]
    H --> I{Makefile発見?}
    I -->|Yes| C
    I -->|No| J[プロジェクト外]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ファイル検索ツール優先度 | fd > ripgrep > find | 常時 |
| BR-02 | キャッシュ有効化 | noninteractive以外でpersistent | 常時 |
| BR-03 | プロジェクト除外 | ~/ はプロジェクトとして認識しない | doom-project-ignored-p |
| BR-04 | 新VCSサポート | Jujutsu(.jj)、Sapling(.sl)を認識 | project.el |

### ファイルインデックスコマンド

fdが利用可能な場合:
```bash
fd . --strip-cwd-prefix -0 -H -E .git -E .jj -tf -tl -c never
```

ripgrepが利用可能な場合:
```bash
rg -0 --files --follow --color=never --hidden -g!.git -g!.jj
```

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

該当なし（ファイルベース）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | インデックス作成失敗 | fd/rg未インストール | findにフォールバック |
| - | プロジェクト未発見 | マーカーなし | プロンプト表示 |

### リトライ仕様

特になし

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

該当なし

## パフォーマンス要件

- fdによる高速ファイルインデックス作成
- キャッシュによるインデックス再利用
- hybridインデックス方式（外部コマンド+Emacs）

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

- MSYSパス変換の無効化（Windows）
- シンボリックリンクの追従

## 備考

- project.elは将来的にprojectileを置き換える可能性
- fdはubuntu/debianでは`fdfind`という名前

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | doom-projects.el | `lisp/doom-projects.el` | 5-20行目の実行ファイル変数 |

**主要変数**:
- **6-10行目**: `doom-fd-executable` - fdコマンドパス
- **12-15行目**: `doom-ripgrep-executable` - rgコマンドパス
- **17-20行目**: `doom-project-cache-dir` - キャッシュディレクトリ

#### Step 2: project.el設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | doom-projects.el | `lisp/doom-projects.el` | 26-38行目のproject.el設定 |

**設定内容**:
- **29行目**: project-list-file設定
- **33-35行目**: Jujutsu/Saplingサポート追加

#### Step 3: projectile設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | doom-projects.el | `lisp/doom-projects.el` | 42-216行目のprojectile設定 |

**主要設定**:
- **49-56行目**: 基本設定（キャッシュ、無視ファイル等）
- **85-86行目**: プロジェクトルートファイル設定
- **163-203行目**: `projectile-generic-command`のカスタマイズ

#### Step 4: def-project-mode!を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | doom-projects.el | `lisp/doom-projects.el` | 226-317行目のマクロ |

**マクロプロパティ**:
- `:modes` - 対象メジャーモード
- `:files` - プロジェクト内ファイル条件
- `:when` - 有効化条件
- `:match` - ファイル名正規表現
- `:add-hooks` - 追加フック
- `:on-load` - 初回読み込み処理
- `:on-enter` - 有効化時処理
- `:on-exit` - 無効化時処理

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

```
projectile-project-root (呼び出し)
    │
    ├─ projectile-root-local
    │
    ├─ projectile-root-bottom-up
    │       └─ projectile-project-root-files-bottom-up 検索
    │
    ├─ projectile-root-top-down
    │       └─ projectile-project-root-files 検索
    │
    └─ projectile-root-top-down-recurring
            └─ projectile-project-root-files-top-down-recurring 検索

projectile-get-ext-command
    │
    └─ doom--only-use-generic-command-a (advice)
            │
            └─ projectile-generic-command (カスタム)
                    │
                    ├─ doom-fd-executable (優先)
                    │
                    ├─ doom-ripgrep-executable (次点)
                    │
                    └─ find (フォールバック)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| doom-projects.el | `lisp/doom-projects.el` | ソース | プロジェクト管理本体 |
| doom.el | `lisp/doom.el` | ソース | コアシステム |
| projectile | packages | 外部パッケージ | プロジェクト管理 |
| project.el | built-in | 組み込み | プロジェクト管理（Emacs標準） |
