# 機能設計書 93-nvm遅延初期化

## 概要

本ドキュメントは、Oh My Zshのnvm遅延初期化機能（lib/nvm.zsh）の設計を記述する。この機能はnvm（Node Version Manager）で管理されているNode.jsのバージョン情報をプロンプトに表示するための関数を提供する。

### 本機能の処理概要

Oh My Zshのnvm遅延初期化機能は、nvmで管理されているNode.jsのバージョン情報をシェルプロンプトに表示するためのヘルパー関数を提供する機能である。

**業務上の目的・背景**：Node.js開発において、プロジェクトごとに異なるNode.jsバージョンを使用することが一般的である。nvmを使用している開発者は、現在どのバージョンのNode.jsがアクティブかを常に把握する必要がある。本機能は、プロンプトにNode.jsバージョンを表示することで、バージョンの誤使用によるトラブルを防止する。

**機能の利用シーン**：
- 複数のNode.jsバージョンを切り替えながら開発を行う際
- プロンプトにNode.jsバージョン情報を表示するテーマを使用する際
- nvm currentコマンドの結果をカスタマイズして表示したい際

**主要な処理内容**：
1. nvmコマンドの存在確認
2. `nvm current`コマンドで現在のNode.jsバージョンを取得
3. バージョン文字列から先頭の'v'を除去
4. テーマ変数（ZSH_THEME_NVM_PROMPT_PREFIX/SUFFIX）で装飾して出力
5. パーセント記号のエスケープ処理

**関連システム・外部連携**：nvm（Node Version Manager）

**権限による制御**：特になし。nvmがインストールされていない場合は関数が即座にreturnする。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCLI機能であり、関連画面はない |

## 機能種別

プロンプト表示 / バージョン情報取得 / ヘルパー関数

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ZSH_THEME_NVM_PROMPT_PREFIX | 環境変数 | No | バージョン表示の前に付加する文字列 | - |
| ZSH_THEME_NVM_PROMPT_SUFFIX | 環境変数 | No | バージョン表示の後に付加する文字列 | - |

### 入力データソース

- **nvmコマンド**: `nvm current`の出力を取得
- **テーマ設定変数**: ZSH_THEME_NVM_PROMPT_PREFIX、ZSH_THEME_NVM_PROMPT_SUFFIX

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| nvm_prompt_info関数出力 | string | 装飾されたNode.jsバージョン文字列 |

### 出力先

- 標準出力（プロンプトに組み込まれる）

## 処理フロー

### 処理シーケンス

```
1. nvm_prompt_info関数呼び出し

2. nvmコマンドの存在確認
   ├─ 存在しない場合: 即座にreturn
   └─ 存在する場合: 次のステップへ

3. nvm currentコマンドの実行
   └─ 出力例: "v18.17.0" または "system" または "none"

4. バージョン文字列の加工
   ├─ 先頭の'v'を除去（${...#v}）
   └─ パーセント記号をエスケープ（${...:gs/%/%%}）

5. 装飾された文字列の出力
   └─ "${ZSH_THEME_NVM_PROMPT_PREFIX}${nvm_prompt}${ZSH_THEME_NVM_PROMPT_SUFFIX}"
```

### フローチャート

```mermaid
flowchart TD
    A[nvm_prompt_info呼び出し] --> B{nvmが<br/>存在?}
    B -->|No| C[return]
    B -->|Yes| D[nvm current実行]
    D --> E[バージョン取得]
    E --> F[先頭の'v'を除去]
    F --> G['%'を'%%'に置換]
    G --> H[PREFIX + version + SUFFIX出力]
    H --> I[終了]
    C --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-93-01 | nvm必須 | nvmが存在しない場合は何も出力しない | 常時 |
| BR-93-02 | バージョン先頭'v'除去 | バージョン文字列から先頭の'v'を除去して表示 | バージョン取得成功時 |
| BR-93-03 | パーセントエスケープ | ZSHプロンプトで使用するため'%'を'%%'にエスケープ | 常時 |
| BR-93-04 | テーマ変数対応 | PREFIX/SUFFIXでバージョン表示をカスタマイズ可能 | テーマ変数設定時 |

### 計算ロジック

バージョン文字列の加工:
- `${$(nvm current)#v}`: 先頭の'v'を除去
- `${...:gs/%/%%}`: すべての'%'を'%%'に置換（グローバル置換）

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | nvm未インストール | nvmコマンドが存在しない | 何も出力せずreturn |
| - | nvmエラー | nvm currentが失敗 | 空または不正な文字列が出力される可能性 |

### リトライ仕様

リトライ処理は実装されていない。

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

該当なし

## パフォーマンス要件

- nvm_prompt_info関数はプロンプト表示のたびに呼び出されるため、軽量である必要がある
- which nvmによるコマンド存在確認は高速
- nvm currentは比較的高速だが、非同期プロンプト機能との組み合わせも検討可能

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

- 外部コマンド（nvm）の出力をそのままプロンプトに使用
- パーセント記号のエスケープにより、ZSHプロンプトエスケープシーケンスの誤動作を防止

## 備考

- nvmはNode.jsのバージョン管理ツールで、~/.nvm/にインストールされることが多い
- 'system'や'none'もnvm currentの出力として返される可能性がある
- テーマによってはnvm_prompt_info関数を呼び出してプロンプトに表示する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | nvm.zsh | `lib/nvm.zsh` | nvm_prompt_info関数の全体構造を理解（全7行） |

**読解のコツ**:
- `which nvm &>/dev/null || return` はZSHの短絡評価を利用したイディオム
- `${...#v}` はパラメータ展開で先頭からパターンを除去
- `${...:gs/%/%%}` はグローバル置換（gsはglobal substituteの略）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | lib/*.zshの読み込みループ（197-199行目）を確認 |
| 2-2 | nvm.zsh | `lib/nvm.zsh` | ファイル全体が関数定義 |

**主要処理フロー**:
1. **1行目**: コメント - 関数の目的説明
2. **2行目**: `function nvm_prompt_info()` - 関数定義開始
3. **3行目**: `which nvm &>/dev/null || return` - nvmの存在確認
4. **4行目**: `local nvm_prompt=${$(nvm current)#v}` - バージョン取得と'v'除去
5. **5行目**: `echo "..."` - 装飾されたバージョン文字列の出力
6. **6行目**: `}` - 関数定義終了

#### Step 3: テーマとの連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | prompt_info_functions.zsh | `lib/prompt_info_functions.zsh` | 類似のprompt_info関数を参照 |

**主要処理フロー**:
- テーマファイル（.zsh-theme）からnvm_prompt_info関数が呼び出される
- ZSH_THEME_NVM_PROMPT_PREFIX/SUFFIXはテーマファイルで定義される

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

```
テーマファイル（.zsh-theme）
    │
    └─ PROMPT変数に$(nvm_prompt_info)を含む
           │
           └─ nvm_prompt_info()（lib/nvm.zsh）
                  │
                  ├─ which nvm
                  │      └─ nvm存在確認
                  │
                  └─ nvm current
                         └─ 現在のNode.jsバージョン取得
```

### データフロー図

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

nvmコマンド ──────────────▶ which nvm ─────▶ 存在確認
                                │
                                v
                         [存在しない] ────▶ return（空出力）
                                │
                                v
                         [存在する]
                                │
                                v
nvm current ─────────────▶ バージョン取得 ─▶ "v18.17.0"
                                │
                                v
                          先頭'v'除去 ────▶ "18.17.0"
                                │
                                v
                          '%'エスケープ ──▶ "18.17.0"
                                │
                                v
ZSH_THEME_NVM_PROMPT_PREFIX ──▶ 装飾 ◀── ZSH_THEME_NVM_PROMPT_SUFFIX
                                │
                                v
                          プロンプト表示 ─▶ "[node:18.17.0]"等
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nvm.zsh | `lib/nvm.zsh` | ソース | nvm_prompt_info関数の定義 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | lib/*.zshの読み込み |
| prompt_info_functions.zsh | `lib/prompt_info_functions.zsh` | ソース | 類似のprompt_info関数群 |
| 各種テーマファイル | `themes/*.zsh-theme` | テーマ | nvm_prompt_infoを呼び出す側 |
