# 機能設計書 12-omz plugin load

## 概要

本ドキュメントは、Oh My Zshの`omz plugin load`コマンドの機能設計について記載する。このコマンドは指定されたプラグインを現在のzshセッションに動的にロードする機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Oh My Zshでは通常、プラグインは`.zshrc`で定義された`$plugins`配列に基づいてシェル起動時に読み込まれる。しかし、新しいプラグインを試したい場合や一時的にプラグインを使用したい場合に、シェルの再起動なしでプラグインをロードできる機能が求められる。本機能は、現在のセッションに対してプラグインを動的にロードすることで、即座にプラグインの機能を利用可能にする。

**機能の利用シーン**：
- 新しいプラグインを試用したい場合（シェル再起動なしで即座に確認）
- 一時的に特定のプラグインの機能を使いたい場合
- `.zshrc`を編集せずにプラグインをテストしたい場合
- プラグイン開発時に変更を即座に反映させたい場合

**主要な処理内容**：
1. 引数で指定されたプラグイン名を受け取る（複数指定可）
2. 各プラグインについて、`$ZSH_CUSTOM/plugins`または`$ZSH/plugins`から検索
3. プラグインディレクトリを`$fpath`に追加
4. プラグインファイル（`*.plugin.zsh`）を`source`で読み込み
5. プラグインに補完ファイルがある場合は`compinit`を再実行

**関連システム・外部連携**：特になし。ローカルファイルシステムのみを参照する。

**権限による制御**：特になし。プラグインディレクトリへの読み取り権限があれば実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | omz plugin load | 主画面 | 指定プラグインを現在のセッションに動的にロード |

## 機能種別

設定変更・動的ロード

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| plugin | 文字列 | Yes | ロードするプラグイン名 | プラグインディレクトリの存在確認 |
| ... | 文字列 | No | 追加のプラグイン名（複数指定可） | 各プラグインについて存在確認 |

### 入力データソース

- `$ZSH_CUSTOM/plugins/$plugin/`ディレクトリ: カスタムプラグインの格納場所（優先）
- `$ZSH/plugins/$plugin/`ディレクトリ: ビルトインプラグインの格納場所

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | - | 標準出力への出力はなし（エラー時のみ警告を出力） |

### 出力先

- 標準エラー出力: 警告メッセージ（プラグインが見つからない場合等）
- シェル環境: `$fpath`への追加、プラグイン関数・エイリアスの定義

### 副作用

- `$fpath`配列にプラグインディレクトリが追加される
- プラグイン内で定義された関数・エイリアス・変数が現在のセッションに追加される
- 補完ファイルがある場合、補完システムが更新される

## 処理フロー

### 処理シーケンス

```
1. 引数の検証
   └─ プラグイン名が指定されているか確認

2. プラグインごとのループ処理
   ├─ プラグインディレクトリの検索
   │   ├─ $ZSH_CUSTOM/plugins/$pluginを確認
   │   └─ $ZSH/plugins/$pluginを確認
   ├─ プラグインの有効性確認
   │   └─ _$plugin または $plugin.plugin.zsh の存在確認
   ├─ $fpathへの追加
   │   └─ 未登録の場合のみ追加
   ├─ 補完ファイルの検出
   │   └─ _* ファイルの存在確認
   └─ プラグインのソース
       └─ $plugin.plugin.zsh を source

3. 補完システムの再初期化
   └─ 補完ファイルがあった場合は compinit -D を実行
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{引数あり?}
    B -->|No| C[使用法を表示して終了]
    B -->|Yes| D[has_completion = 0]
    D --> E[各プラグインをループ]
    E --> F{$ZSH_CUSTOM/plugins/$pluginに存在?}
    F -->|Yes| G[base = $ZSH_CUSTOM/plugins/$plugin]
    F -->|No| H{$ZSH/plugins/$pluginに存在?}
    H -->|Yes| I[base = $ZSH/plugins/$plugin]
    H -->|No| J[警告: プラグインが見つからない]
    J --> K[次のプラグインへ]
    G --> L{有効なプラグイン?}
    I --> L
    L -->|No| M[警告: 無効なプラグイン]
    M --> K
    L -->|Yes| N{$baseは$fpathに未登録?}
    N -->|Yes| O[$fpathの先頭に$baseを追加]
    N -->|No| P[スキップ]
    O --> Q{補完ファイル _* あり?}
    P --> Q
    Q -->|Yes| R[has_completion = 1]
    Q -->|No| S{$plugin.plugin.zshあり?}
    R --> S
    S -->|Yes| T[source $base/$plugin.plugin.zsh]
    S -->|No| U[次のプラグインへ]
    T --> K
    U --> K
    K --> V{全プラグイン処理完了?}
    V -->|No| E
    V -->|Yes| W{has_completion = 1?}
    W -->|Yes| X[compinit -D -d $_comp_dumpfile]
    W -->|No| Y[終了]
    X --> Y
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | カスタム優先検索 | `$ZSH_CUSTOM/plugins`を先に検索し、見つからない場合のみ`$ZSH/plugins`を検索 | 常時 |
| BR-02 | プラグイン有効性判定 | `_$plugin`ファイルまたは`$plugin.plugin.zsh`ファイルが存在するディレクトリを有効なプラグインと判定 | 常時 |
| BR-03 | fpath重複回避 | 既に`$fpath`に登録されているディレクトリは追加しない | 常時 |
| BR-04 | 補完キャッシュ保持 | `compinit -D`オプションにより、現在のセッション限定で補完を更新（dumpファイルは更新しない） | 補完ファイル検出時 |

### 計算ロジック

特になし。

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

本機能ではデータベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 引数なしエラー | プラグイン名が指定されていない | 使用法を表示して終了（リターンコード1） |
| - | プラグイン未検出警告 | 指定されたプラグインが見つからない | 警告を出力して次のプラグインの処理を継続 |
| - | 無効プラグイン警告 | プラグインディレクトリは存在するが、必要なファイルがない | 警告を出力して次のプラグインの処理を継続 |

### リトライ仕様

リトライは行わない。

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

該当なし。ただし、複数プラグイン指定時は途中でエラーが発生しても、他のプラグインの処理は継続される。

## パフォーマンス要件

- 1プラグインあたりのロード時間は、プラグインの複雑さに依存
- 補完ファイルがある場合、`compinit`の再実行に追加時間がかかる

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

- プラグインのソースコードを直接実行するため、信頼できるプラグインのみを使用すること
- `$ZSH_CUSTOM`に配置されたカスタムプラグインは、ユーザーの責任で管理される
- ビルトインプラグインはOh My Zshプロジェクトでレビューされている

## 備考

- 本機能でロードしたプラグインは現在のセッションでのみ有効
- 永続的にプラグインを有効化するには`omz plugin enable`を使用する
- `-D`オプションによりcompinit時にdumpファイルを更新しないため、次回セッション起動時には影響しない

---

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

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

### 推奨読解順序

#### Step 1: 関数の全体構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | `_omz::plugin::load`関数の定義位置（493-539行目）を確認 |

**読解のコツ**: zshの配列記法`${fpath[(Ie)$base]}`は、`$fpath`配列内で`$base`のインデックスを返す。0の場合は存在しない。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | omz関数（3-21行目）からのコマンドディスパッチを確認 |
| 2-2 | cli.zsh | `lib/cli.zsh` | _omz::plugin関数（205-226行目）からのサブコマンドディスパッチを確認 |

**主要処理フロー**:
1. **3-21行目**: `omz`関数がコマンドライン引数を解析し、`_omz::$command`を呼び出す
2. **205-226行目**: `_omz::plugin`関数が`load`サブコマンドを受け取り、`_omz::plugin::load`を呼び出す

#### Step 3: プラグインロード処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | `_omz::plugin::load`関数（493-539行目）の実装詳細 |

**主要処理フロー**:
- **494-497行目**: 引数チェックと使用法表示
- **499行目**: ローカル変数の宣言（`has_completion`フラグ）
- **500-508行目**: プラグインディレクトリの検索処理
- **511-517行目**: プラグインの有効性確認と`$fpath`への追加
- **520-522行目**: 補完ファイルの検出
- **525-527行目**: プラグインファイルの`source`
- **536-538行目**: 補完システムの再初期化

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

```
omz (3-21行目)
    │
    └─ _omz::plugin (205-226行目)
           │
           └─ _omz::plugin::load (493-539行目)
                  │
                  ├─ プラグインディレクトリ検索
                  │      └─ $ZSH_CUSTOM/plugins → $ZSH/plugins
                  │
                  ├─ $fpathへの追加
                  │
                  ├─ source $base/$plugin.plugin.zsh
                  │
                  └─ compinit -D (補完ファイルがある場合)
```

### データフロー図

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

プラグイン名         ───▶ ディレクトリ検索              ───▶ $fpath更新
(コマンドライン)           │
                          ├─ $ZSH_CUSTOM優先
                          └─ $ZSH/pluginsフォールバック
                               │
                               ▼
                          プラグインsource            ───▶ 関数・エイリアス定義
                               │
                               ▼
                          compinit（必要時）          ───▶ 補完システム更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omzコマンドのCLI実装。_omz::plugin::load関数を含む |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | $fpath、$pluginsの初期設定を行うメインスクリプト |
| completion.zsh | `lib/completion.zsh` | ソース | compinit設定と$_comp_dumpfile変数の定義 |
