# バッチ設計書 6-doom sync

## 概要

本ドキュメントは、Doom Emacsの設定を同期するためのCLIコマンド`doom sync`の設計仕様を定義するものである。

### 本バッチの処理概要

`doom sync`は、Doom Emacsの設定とパッケージを同期するための包括的なコマンドである。autoremove、install、autoloads、recompileの機能を組み合わせて実行し、設定変更後にDoom Emacsを正しい状態に保つ。

**業務上の目的・背景**：Doom Emacsは多数のパッケージとモジュールで構成されており、設定変更（doom!ブロックの編集、package!ブロックの追加/削除、autoload関数の変更等）を行った後は、パッケージのインストール/削除、autoloadファイルの再生成、バイトコンパイルの更新が必要となる。`doom sync`は、これらの複雑な同期作業を単一のコマンドで自動化し、設定とランタイム状態の整合性を保証する。

**バッチの実行タイミング**：以下の場合に実行が推奨される：
- doom!ブロックを変更した時
- package!ブロックを追加/削除/変更した時
- autoload関数を追加/削除/変更した時
- Doomを手動で更新した時（git pull）
- Doom設定を別の場所に移動した時
- Emacsをアップグレード/ダウングレードした時

**主要な処理内容**：
1. 実行中の他のEmacsプロセスの検出
2. プロファイル同期（doom-profiles-bootloadable-p の場合）
3. 環境変数ファイルの再生成（既存の場合）
4. パッケージのインストール/リビルド
5. パッケージの更新（-u オプション時）
6. ガベージコレクション（孤立パッケージの削除）
7. プロファイルの生成
8. 同期情報ファイルの更新

**前後の処理との関連**：`doom install`後の定期的なメンテナンス、`doom upgrade`の内部で呼び出される、`doom gc`を内部で呼び出す。

**影響範囲**：パッケージディレクトリ（straight/build, straight/repos）、プロファイルデータ、バイトコンパイル済みファイル、環境変数ファイル。

## バッチ種別

設定同期 / パッケージ管理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（設定変更時） |
| 実行時刻 | ユーザー任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動（設定変更後） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Doom Emacs インストール済み | doom install が完了していること |
| Git 利用可能 | straight.el がパッケージリポジトリを管理するため |
| ネットワーク接続 | 新しいパッケージのインストール/更新時に必要 |

### 実行可否判定

1. Doom Emacsが正しくインストールされていること
2. doom-packages-ensure 関数が実行可能であること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| -e | フラグ | No | false | 環境変数ファイルを再生成しない |
| -u | フラグ | No | false | インストール済みパッケージを更新 |
| -U | フラグ | No | false | パッケージを更新しない |
| --gc | フラグ | No | false | 孤立パッケージを削除しリグラフト |
| -j, --jobs | 数値 | No | 最大スレッド数 | ネイティブコンパイルのスレッド数 |
| -b, --rebuild | フラグ | No | false | 全パッケージを無条件でリビルド |
| -B | フラグ | No | false | ホスト名/Emacsバージョン変更時もリビルドしない |
| --aot | フラグ | No | false | 事前ネイティブコンパイルを有効化 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| $DOOMDIR/init.el | Emacs Lisp | doom!ブロック定義 |
| $DOOMDIR/packages.el | Emacs Lisp | package!ブロック定義 |
| doom-sync-info-file | Lisp | 前回同期時のEmacs情報 |
| doom-env-file | Lisp | 環境変数ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 同期進捗とステータスメッセージ |
| straight/build/ | ディレクトリ | ビルドされたパッケージ |
| straight/repos/ | ディレクトリ | パッケージリポジトリ |
| doom-sync-info-file | Lisp | 同期情報（Emacsバージョン、システムハッシュ） |
| プロファイルデータ | Lisp | 生成されたプロファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | sync（doom-profile-data-dir内） |
| 出力先 | $EMACSDIR/.local/etc/@/ |
| 文字コード | UTF-8 |
| 形式 | Lispフォーム (cons emacs-version system-hash) |

## 処理フロー

### 処理シーケンス

```
1. 前処理
   └─ 他のEmacsプロセスの検出（非バッチ）
   └─ プロファイル同期（bootloadable時）
   └─ doom-before-sync-hook の実行
   └─ 中断時警告フックの設定

2. バージョン/システムチェック
   └─ 前回同期時のEmacs情報読み込み
   └─ Emacsバージョン変更の検出
   └─ システムハッシュ変更の検出
   └─ リビルド必要性の判定

3. 環境変数ファイル処理
   └─ 既存の場合、doom env コマンドを呼び出し

4. パッケージ同期
   └─ doom-packages-ensure でパッケージをインストール/リビルド

5. パッケージ更新（オプション）
   └─ doom-packages-update を呼び出し

6. ガベージコレクション
   └─ doom gc を呼び出し（オプションに応じて制限）

7. プロファイル生成
   └─ doom-profile-generate を呼び出し
   └─ 他のEmacsが実行中なら再起動を促すメッセージ表示

8. 同期情報の保存
   └─ doom-sync-info-file に情報を書き込み

9. 後処理
   └─ doom-after-sync-hook の実行
   └─ 中断時警告フックの解除
```

### フローチャート

```mermaid
flowchart TD
    A[doom sync 開始] --> B[他のEmacsプロセス検出]
    B --> C{プロファイルブートローダブル?}
    C -->|Yes| D[プロファイル同期]
    C -->|No| E[before-sync-hook実行]
    D --> E
    E --> F{前回のEmacs情報確認}
    F --> G{バージョン/システム変更?}
    G -->|Yes| H[リビルド確認]
    G -->|No| I[環境変数ファイル確認]
    H --> I
    I -->|存在する| J[doom env 実行]
    I -->|存在しない| K[パッケージ同期]
    J --> K
    K --> L{-u オプション?}
    L -->|Yes| M[パッケージ更新]
    L -->|No| N[doom gc 実行]
    M --> N
    N --> O[プロファイル生成]
    O --> P{他のEmacs実行中?}
    P -->|Yes| Q[再起動メッセージ表示]
    P -->|No| R[同期情報保存]
    Q --> R
    R --> S[after-sync-hook実行]
    S --> T[終了]
```

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

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

本コマンドはデータベースを使用しない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

### テーブル別操作詳細

データベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 非ゼロ | パッケージエラー | パッケージのインストール/ビルド失敗 | ネットワーク接続確認、doom doctor実行 |
| 非ゼロ | 中断エラー | Ctrl+C等で処理が中断された | doom sync を再実行 |
| 非ゼロ | 環境エラー | Git/Emacsの環境問題 | doom doctor で診断 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動再実行） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. 中断時は「doom sync to repair it」のメッセージが表示される
2. `doom doctor`で環境診断
3. 必要に応じて`doom sync --rebuild`で全パッケージをリビルド

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 同期処理全体 |
| コミットタイミング | 各ステップ完了時 |
| ロールバック条件 | 中断時は不完全な状態で終了（再実行で修復） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | パッケージ数に依存（通常数十〜数百） |
| 目標処理時間 | 初回: 数分〜十数分、更新: 数十秒〜数分 |
| メモリ使用量上限 | Emacsプロセス + コンパイル処理分 |

## 排他制御

- 同時に複数の`doom sync`を実行することは推奨されない
- straight.el のロック機構が働く
- 他のEmacsプロセスが実行中でも動作するが、再起動が必要

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | コマンド開始時 | 使用するEmacs情報、プロファイル名 |
| 進捗ログ | 処理中 | 各パッケージのインストール/ビルド状況 |
| 警告ログ | バージョン変更時 | Emacsバージョン/システム変更の警告 |
| 終了ログ | コマンド終了時 | ベンチマーク結果 |
| エラーログ | 中断時 | 中断警告メッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | ベンチマーク表示 | 標準出力 |
| 中断検知 | 中断時 | 標準出力（警告メッセージ） |

## 備考

- `doom-after-sync-hook`と`doom-before-sync-hook`でユーザーカスタマイズ可能
- `doom-sync--system-hash`はdoom-local-dirとsystem-configurationのMD5ハッシュ
- `:benchmark t`により処理時間が自動的に計測される
- `doom-sync--abort-warning-h`により中断時に警告が表示される
- 3.0.0以降、`doom build`は`doom sync --rebuild`に、`doom purge`は`doom gc`に統合
