# 機能設計書 1-Oh My Zsh初期化

## 概要

本ドキュメントは、Oh My Zsh（以下OMZ）の起動時初期化処理に関する機能設計書である。oh-my-zsh.shを起動時に読み込み、ZSH環境変数、キャッシュディレクトリ、fpath、プラグイン、テーマを初期化する処理について記述する。

### 本機能の処理概要

本機能は、ZSHシェル起動時にOMZフレームワーク全体を初期化するエントリーポイントである。ユーザーの.zshrcからsourceされることで実行される。

**業務上の目的・背景**：ZSHシェルをより便利で生産性の高いものにするため、プラグインシステム、テーマシステム、補完システム等の各種機能を統一的に初期化する必要がある。本機能により、ユーザーは複雑な設定を意識することなく、豊富な機能を利用できる環境を構築できる。

**機能の利用シーン**：新しいターミナルを開いてZSHシェルを起動するたびに自動的に実行される。ユーザーが明示的に呼び出すことはなく、.zshrcに記述された`source $ZSH/oh-my-zsh.sh`により暗黙的に実行される。

**主要な処理内容**：
1. ZSH実行環境の検証（ZSHシェルで実行されているか、emulationモードでないか）
2. 環境変数の初期化（ZSH、ZSH_CUSTOM、ZSH_CACHE_DIR）
3. fpathへの関数/補完ディレクトリ追加
4. 更新チェック処理の呼び出し
5. プラグインのfpathへの登録と読み込み
6. 補完システムの初期化（compinit）
7. ライブラリファイルの読み込み
8. カスタム設定ファイルの読み込み
9. テーマの読み込み

**関連システム・外部連携**：Gitリポジトリとの連携（バージョン管理、更新チェック）、GitHub API（更新確認時）

**権限による制御**：特になし。ただし、ZSH_CACHE_DIRへの書き込み権限がない場合は$HOME/.cache/oh-my-zshにフォールバックする。

## 関連画面

本機能は画面を持たないバックエンド処理であり、直接関連する画面はない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | シェル起動時に自動実行 |

## 機能種別

初期化処理 / 環境構築

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ZSH | 環境変数(文字列) | No | OMZインストールディレクトリ | 未定義時はスクリプトパスから自動設定 |
| ZSH_CUSTOM | 環境変数(文字列) | No | カスタム設定ディレクトリ | 未定義時は$ZSH/custom |
| ZSH_CACHE_DIR | 環境変数(文字列) | No | キャッシュディレクトリ | 未定義時は$ZSH/cache、書き込み不可時は$HOME/.cache/oh-my-zsh |
| ZSH_THEME | 環境変数(文字列) | No | 使用するテーマ名 | テーマファイルが存在すること |
| plugins | 配列変数 | No | 有効化するプラグインリスト | 各プラグインディレクトリが存在すること |
| ZSH_DISABLE_COMPFIX | 環境変数(boolean) | No | 補完セキュリティチェックの無効化 | true/false |
| ZSH_COMPDUMP | 環境変数(文字列) | No | 補完ダンプファイルパス | 未定義時は自動生成 |

### 入力データソース

- ユーザーの.zshrcファイル（環境変数とplugins配列の定義）
- $ZSH/plugins/以下のプラグインファイル
- $ZSH_CUSTOM/以下のカスタム設定ファイル
- $ZSH/themes/以下のテーマファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| fpath | 配列 | 関数検索パス（補完関数等） |
| ZSH | 環境変数 | OMZインストールディレクトリ |
| ZSH_CUSTOM | 環境変数 | カスタム設定ディレクトリ |
| ZSH_CACHE_DIR | 環境変数 | キャッシュディレクトリ |
| ZSH_COMPDUMP | 環境変数 | 補完ダンプファイルパス |
| SHORT_HOST | 変数 | 短縮ホスト名 |

### 出力先

- シェル環境（変数、関数、エイリアス等の設定）
- $ZSH_COMPDUMP（補完キャッシュファイル）
- $ZSH_CACHE_DIR/completions/（補完キャッシュディレクトリ）

## 処理フロー

### 処理シーケンス

```
1. 実行環境検証
   └─ ZSHシェルで実行されているか確認（非ZSH時はエラー出力して終了）
   └─ emulationモードでないか確認

2. 環境変数初期化
   └─ ZSH: スクリプトパスから設定（未定義時）
   └─ ZSH_CUSTOM: $ZSH/customに設定（未定義時）
   └─ ZSH_CACHE_DIR: $ZSH/cacheに設定（未定義時、書き込み不可時はフォールバック）

3. キャッシュディレクトリ作成
   └─ $ZSH_CACHE_DIR/completionsディレクトリ作成
   └─ fpathに追加

4. 更新チェック
   └─ tools/check_for_upgrade.shをsource

5. fpath設定
   └─ $ZSH/functions, $ZSH/completions追加
   └─ $ZSH_CUSTOM/functions, $ZSH_CUSTOM/completions追加

6. プラグインfpath登録
   └─ plugins配列をループ
   └─ 各プラグインのディレクトリをfpathに追加

7. 補完システム初期化
   └─ compaudit, compinit, zrecompileをautoload
   └─ zcompdumpメタデータ検証
   └─ compinit実行
   └─ zcompdumpファイルのコンパイル

8. ライブラリ読み込み
   └─ $ZSH/lib/*.zshを順次source

9. プラグイン読み込み
   └─ plugins配列の各プラグインをsource

10. カスタム設定読み込み
    └─ $ZSH_CUSTOM/*.zshを順次source

11. テーマ読み込み
    └─ $ZSH_THEME変数で指定されたテーマをsource
```

### フローチャート

```mermaid
flowchart TD
    A[シェル起動] --> B{ZSHで実行?}
    B -->|No| C[エラー出力・終了]
    B -->|Yes| D{emulationモード?}
    D -->|Yes| C
    D -->|No| E[環境変数初期化]
    E --> F[キャッシュディレクトリ作成]
    F --> G[更新チェック実行]
    G --> H[fpath設定]
    H --> I[プラグインfpath登録]
    I --> J[compinit実行]
    J --> K[ライブラリ読み込み]
    K --> L[プラグイン読み込み]
    L --> M[カスタム設定読み込み]
    M --> N{テーマ指定あり?}
    N -->|Yes| O[テーマ読み込み]
    N -->|No| P[初期化完了]
    O --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ZSH実行必須 | ZSHシェル以外での実行を禁止する | 常時 |
| BR-02 | emulationモード禁止 | zsh emulationモードでの実行を禁止する | 常時 |
| BR-03 | キャッシュフォールバック | ZSH_CACHE_DIRが書き込み不可の場合$HOME/.cache/oh-my-zshを使用 | ZSH_CACHE_DIRへの書き込み権限なし |
| BR-04 | プラグイン存在チェック | 存在しないプラグイン指定時は警告を出力して継続 | プラグイン読み込み時 |
| BR-05 | テーマ存在チェック | 存在しないテーマ指定時は警告を出力して継続 | テーマ読み込み時 |
| BR-06 | 補完キャッシュ再生成 | OMZリビジョンまたはfpathが変更された場合にzcompdumpを再生成 | compinit実行時 |

### 計算ロジック

**zcompdumpパス生成**:
```
ZSH_COMPDUMP = ${ZDOTDIR:-$HOME}/.zcompdump-${SHORT_HOST}-${ZSH_VERSION}
```

**SHORT_HOST算出**:
- macOS: `scutil --get LocalHostName` または `${HOST/.*/}`
- その他: `${HOST/.*/}`

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 非ZSH実行エラー | ZSH以外のシェルで実行 | プロセスツリーを表示してreturn 1 |
| - | emulationモードエラー | emulationモードで実行 | エラーメッセージ出力してreturn 1 |
| - | プラグイン未検出警告 | 指定プラグインが存在しない | 警告メッセージ出力して継続 |
| - | テーマ未検出警告 | 指定テーマが存在しない | 警告メッセージ出力して継続 |

### リトライ仕様

リトライは行わない。

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

本機能はトランザクションを使用しない。

## パフォーマンス要件

- シェル起動時間への影響を最小限に抑える
- zcompdumpファイルのコンパイルにより補完の高速化を図る
- 非同期での補完セキュリティチェック実行（`&|`によるバックグラウンド実行）

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

- **補完セキュリティチェック**: `compaudit`により補完ファイルのパーミッションを検証
- **安全でないディレクトリからの読み込み制限**: `ZSH_DISABLE_COMPFIX`がtrueでない場合、`compinit -i`で安全なディレクトリのみから補完を読み込む
- **グループ/他者書き込み可能ディレクトリの警告**: 不適切なパーミッションの補完ディレクトリを検出して警告

## 備考

- oh-my-zsh.shは`.zshrc`から`source`されることを前提としている
- プラグインの読み込み順序は`plugins`配列の定義順に依存する
- `_omz_source`関数により、エイリアスの無効化設定（zstyle）に対応している

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

本機能で扱う主要な変数と配列の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | 環境変数（ZSH, ZSH_CUSTOM, ZSH_CACHE_DIR, plugins, ZSH_THEME）の定義と用途 |

**読解のコツ**: ZSHの変数展開記法に注目。`${var:-default}`は未定義時のデフォルト値、`${(%):-%x}`はプロンプト展開によるスクリプトパス取得。

#### Step 2: エントリーポイントを理解する

処理の起点となるファイル・関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | ファイル全体が初期化処理のエントリーポイント |

**主要処理フロー**:
1. **3-8行目**: `omz_f`関数定義（ANSIフォーマット用ユーティリティ）
2. **10-39行目**: 非ZSH実行時のエラー処理（プロセスツリー表示機能付き）
3. **41-46行目**: emulationモードチェック
4. **50-68行目**: 環境変数初期化（ZSH, ZSH_CUSTOM, ZSH_CACHE_DIR, fpath）
5. **71行目**: 更新チェック処理の呼び出し
6. **78-98行目**: プラグインのfpath登録
7. **108-152行目**: 補完システム初期化（compinit, zcompdump管理）
8. **154-193行目**: `_omz_source`関数定義（エイリアス制御付きsource）
9. **195-206行目**: ライブラリとプラグインの読み込み
10. **208-231行目**: カスタム設定とテーマの読み込み

#### Step 3: 環境検証処理を理解する

ZSH実行環境の検証ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | 10-46行目の検証処理 |

**主要処理フロー**:
- **11行目**: `[ -n "$ZSH_VERSION" ]`でZSH実行を判定
- **12-27行目**: `omz_ptree`関数でプロセスツリーを取得（デバッグ用）
- **43行目**: `emulate`コマンドでemulationモードをチェック

#### Step 4: 補完システム初期化を理解する

compinit周りの処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | 108-152行目のcompinit処理 |
| 4-2 | compfix.zsh | `lib/compfix.zsh` | 補完セキュリティチェック処理 |

**主要処理フロー**:
- **109-111行目**: ZSH_COMPDUMPパス生成
- **114-122行目**: zcompdumpメタデータ検証（リビジョン、fpath）
- **124-133行目**: compinit実行（-i: セキュアモード、-u: 非セキュアモード）
- **136-145行目**: zcompdumpへのメタデータ追記
- **148-152行目**: zcompdumpのコンパイル（.zwc生成）

#### Step 5: _omz_source関数を理解する

エイリアス制御付きのsource処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | 154-193行目の_omz_source関数 |

**主要処理フロー**:
- **157-161行目**: zstyleコンテキストの構築（lib:名前 または plugins:名前）
- **164行目**: zstyleによるエイリアス無効化設定の取得
- **167-171行目**: 既存エイリアスのバックアップ
- **173-178行目**: ファイルのsource（ZSH_CUSTOM優先）
- **181-192行目**: エイリアス無効化設定時のエイリアス復元

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

```
oh-my-zsh.sh (エントリーポイント)
    │
    ├─ omz_f() - ANSIフォーマット関数
    │
    ├─ omz_ptree() - プロセスツリー表示（エラー時のみ）
    │
    ├─ tools/check_for_upgrade.sh - 更新チェック
    │      └─ handle_update()
    │      └─ is_update_available()
    │
    ├─ is_plugin() - プラグイン存在チェック
    │
    ├─ compinit - 補完システム初期化
    │
    ├─ lib/compfix.zsh
    │      └─ handle_completion_insecurities()
    │             └─ compaudit
    │
    ├─ _omz_source() - エイリアス制御付きsource
    │      ├─ lib/*.zsh - ライブラリファイル群
    │      └─ plugins/*/*.plugin.zsh - プラグインファイル群
    │
    ├─ $ZSH_CUSTOM/*.zsh - カスタム設定ファイル
    │
    └─ is_theme() - テーマ存在チェック
           └─ $ZSH_THEME.zsh-theme - テーマファイル
```

### データフロー図

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

.zshrc
  │
  ├─ ZSH変数          ───▶ oh-my-zsh.sh
  ├─ ZSH_CUSTOM変数         │
  ├─ ZSH_CACHE_DIR変数      ├─▶ 環境変数設定 ───────────────▶ シェル環境
  ├─ plugins配列            │
  └─ ZSH_THEME変数          ├─▶ fpath構築 ──────────────────▶ fpath配列
                            │
$ZSH/plugins/         ───▶ プラグイン読み込み ──────────────▶ 関数・エイリアス定義
                            │
$ZSH/lib/             ───▶ ライブラリ読み込み ──────────────▶ 関数・設定定義
                            │
$ZSH_CUSTOM/*.zsh     ───▶ カスタム設定読み込み ────────────▶ ユーザー設定適用
                            │
$ZSH/themes/          ───▶ テーマ読み込み ──────────────────▶ プロンプト設定
                            │
compinit              ───▶ 補完初期化 ──────────────────────▶ $ZSH_COMPDUMP
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | メインエントリーポイント、初期化処理全体 |
| check_for_upgrade.sh | `tools/check_for_upgrade.sh` | ソース | 自動更新チェック処理 |
| compfix.zsh | `lib/compfix.zsh` | ソース | 補完セキュリティチェック |
| cli.zsh | `lib/cli.zsh` | ソース | omzコマンドCLI（初期化時に読み込まれる） |
| *.zsh | `lib/*.zsh` | ソース | 各種ライブラリ機能 |
| *.plugin.zsh | `plugins/*/*.plugin.zsh` | ソース | 各プラグインの実装 |
| *.zsh-theme | `themes/*.zsh-theme` | ソース | 各テーマの実装 |
| .zshrc | `~/.zshrc` | 設定 | ユーザー設定ファイル（本機能を呼び出す） |
| .zcompdump-* | `~/.zcompdump-*` | キャッシュ | 補完キャッシュファイル |
