# 機能設計書 10-パッケージ管理（straight）

## 概要

本ドキュメントは、Doom Emacsのパッケージ管理システム（doom-straight.el）の機能設計を記述する。このシステムは、straight.elパッケージマネージャを活用した宣言的・遅延読み込み・再現可能なパッケージ管理を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Emacsの標準パッケージマネージャ（package.el）は、ダウンタイムやビルドエラー、TLSの問題など、様々な問題を抱えている。straight.elを採用することで、GitHubからの直接クローン、バージョンのピン留め、ローリングリリースなど、より堅牢なパッケージ管理を実現する。

**機能の利用シーン**：
- `doom sync`: パッケージの同期とプロファイル再生成
- `doom upgrade`: Doom Emacsとパッケージの更新
- パッケージのインストール・更新・削除
- バージョンロックファイルによる再現可能な環境構築

**主要な処理内容**：
1. straight.elの設定とカスタマイズ
2. パッケージピン留め（doom-package-pinned-alist）
3. VCエラーのリトライ機構
4. プロンプトの自動応答
5. ネイティブコンパイルの制御
6. クローン失敗時のエラーハンドリング

**関連システム・外部連携**：straight.el、git、doom-cli.el

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI操作のため直接的な画面関連なし |

## 機能種別

パッケージ管理 / バージョン管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| straight-base-dir | string | No | straight.elのベースディレクトリ | ディレクトリ |
| straight-repository-branch | string | No | straight.elのリポジトリブランチ | ブランチ名 |
| straight-build-dir | string | No | ビルドディレクトリ名 | 文字列 |

### 入力データソース

- packages.el（各モジュールの）
- ロックファイル
- Gitリポジトリ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| パッケージインストール | side-effect | straight-base-dirへのインストール |
| ビルド成果物 | files | straight-build-dirへのビルド |
| ログ出力 | message | 進捗・エラーメッセージ |

### 出力先

- $DOOMLOCAL/straight/
- ログファイル

## 処理フロー

### パッケージ同期

```
1. packages.elファイルの読み込み
   └─ モジュールごとのpackage!宣言を収集
2. ロックファイルの読み込み
   └─ バージョンピン情報を取得
3. パッケージのクローン/更新
   └─ straight-vc-clone/straight-vc-fetch
4. パッケージのビルド
   └─ autoloads生成、バイトコンパイル
5. プロファイルの生成
   └─ doom sync完了
```

### フローチャート

```mermaid
flowchart TD
    A[doom sync実行] --> B[packages.el読み込み]
    B --> C[ロックファイル読み込み]
    C --> D{新規パッケージ?}
    D -->|Yes| E[git clone]
    D -->|No| F{更新必要?}
    F -->|Yes| G[git fetch/merge]
    F -->|No| H[スキップ]
    E --> I{クローン成功?}
    I -->|No| J[リトライ（最大3回）]
    J --> I
    I -->|Yes| K[ビルド]
    G --> K
    H --> L[完了]
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ブランチ | developブランチを使用 | straight-repository-branch |
| BR-02 | ビルドディレクトリ | Emacsバージョン別 | straight-build-dir |
| BR-03 | シャロークローン | 深度1でクローン | straight-vc-git-default-clone-depth |
| BR-04 | 変更チェック無効 | 起動時間短縮のため | straight-check-for-modifications |
| BR-05 | リトライ回数 | VCエラー時最大3回 | +doom-straight-retries |

### 自動応答オプション

| プロンプト | 選択される応答 |
|-----------|---------------|
| has diverged from | Reset branch |
| but recipe specifies a URL of | Delete remote, re-create |
| has a merge conflict | Abort merge |
| has a dirty worktree | Discard changes |
| is ahead of default branch | Checkout branch |

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

該当なし（Gitベース）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | クローン失敗 | ネットワークエラー | リトライ（3回） |
| - | マージコンフリクト | ローカル変更と衝突 | 自動マージ中止 |
| - | 空ディレクトリ | クローン不完全 | ディレクトリ削除後再クローン |

### リトライ仕様

| メソッド | リトライ対象 |
|---------|-------------|
| clone | Yes |
| normalize | Yes |
| fetch-from-remote | Yes |
| fetch-from-upstream | Yes |
| merge-from-remote | Yes |
| merge-from-upstream | Yes |

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

該当なし（Git操作は原子的）

## パフォーマンス要件

- シャロークローンによる初回インストール時間短縮
- straight-check-for-modifications = nil による起動時間短縮
- 遅延ネイティブコンパイル

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

- GIT_CONFIG_NOSYSTEM = 1（システム設定の無視）
- GIT_CONFIG_GLOBAL = /dev/null（グローバル設定の無視）
- ログファイル権限: #o600

## 備考

- package.elのパッケージはdoom syncで削除される
- let-alistはEmacs 26+では組み込み

---

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

### 推奨読解順序

#### Step 1: straight設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | doom-straight.el | `lisp/doom-straight.el` | 39-58行目の基本設定 |

**主要設定**:
- **39行目**: `straight-base-dir` = doom-local-dir
- **40行目**: `straight-repository-branch` = "develop"
- **44行目**: `straight-build-dir` = "build-{emacs-version}"
- **45行目**: `straight-cache-autoloads` = nil
- **49行目**: `straight-check-for-modifications` = nil
- **58行目**: `straight-vc-git-default-clone-depth` = '(1 single-branch)

#### Step 2: ピン留め機構を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | doom-straight.el | `lisp/doom-straight.el` | 74-78行目 |

**処理内容**:
- `doom--read-pinned-packages-a`がロックファイルとdoom-packagesの両方からピン情報を読み取る

#### Step 3: 自動応答を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | doom-straight.el | `lisp/doom-straight.el` | 101-124行目 |

**自動応答ルール**:
- `doom-straight--auto-options`でプロンプトと応答のマッピングを定義
- 非インタラクティブ時に自動選択

#### Step 4: リトライ機構を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | doom-straight.el | `lisp/doom-straight.el` | 292-324行目 |

**リトライ処理**:
- **292-293行目**: `+doom-straight-retries` = 3
- **295-302行目**: `+doom-straight-retry-methods`
- **304-324行目**: `doom-straight--retry-a`

#### Step 5: クローンエラー検出を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | doom-straight.el | `lisp/doom-straight.el` | 330-343行目 |

**処理内容**:
- クローン後に.gitディレクトリが存在するか確認
- 不完全なクローンは削除して再試行を強制

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

```
doom sync (CLI)
    │
    └─ straight.el
            │
            ├─ straight-vc-clone
            │       │
            │       └─ doom-straight--retry-a (advice)
            │               └─ リトライ処理
            │
            ├─ straight-vc-fetch
            │       └─ doom-straight--retry-a
            │
            ├─ straight--build-autoloads
            │       └─ doom-straight--no-compute-prefixes-a (advice)
            │
            └─ straight--popup-raw
                    └─ doom-straight--fallback-to-tty-prompt-a (advice)
                            └─ doom-straight--auto-options参照
```

### データフロー図

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

packages.el ──────────▶ package!マクロ展開 ──────────▶ doom-packages
                          │
lockfile ─────────────▶ straight--lockfile-read-all ──▶ ピン情報
                          │
                          └─ doom--read-pinned-packages-a

ピン情報 + レシピ ────▶ straight.el処理 ─────────────▶ パッケージ
                          │                              インストール
                          ├─ git clone
                          │
                          ├─ git fetch
                          │
                          └─ ビルド

パッケージ ───────────▶ doom sync完了 ───────────────▶ プロファイル
                                                         生成
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| doom-straight.el | `lisp/doom-straight.el` | ソース | パッケージ管理本体 |
| doom.el | `lisp/doom.el` | ソース | コアシステム |
| straight.el | packages | 外部パッケージ | パッケージマネージャ |
| packages.el | modules/*/packages.el | 設定 | パッケージ宣言 |
