# 機能設計書 10-omz plugin info

## 概要

本ドキュメントは、Oh My Zsh（以下OMZ）のプラグイン情報表示機能「omz plugin info」コマンドに関する機能設計書である。プラグインのREADME.mdを表示する処理について記述する。

### 本機能の処理概要

本機能は、ユーザーが指定したプラグインのREADME.mdファイルを読み込み、適切な形式で表示する。glowやbat等のツールが利用可能な場合は、それらを使用してリッチな表示を行う。

**業務上の目的・背景**：OMZには350以上のプラグインが用意されており、各プラグインの使い方や設定方法を簡単に確認できる仕組みが必要である。プラグインを有効化する前に内容を確認したり、使用中のプラグインのリファレンスとして利用される。

**機能の利用シーン**：
- 新しいプラグインの機能を確認する時
- プラグインの設定方法を調べる時
- プラグインが提供するエイリアスやショートカットを確認する時

**主要な処理内容**：
1. 指定プラグインの存在確認
2. README.mdファイルの検索
3. 適切なビューアでの表示（glow/bat/less/cat）

**関連システム・外部連携**：glow、bat、less等の外部ツール（オプション）

**権限による制御**：プラグインディレクトリへの読み取り権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | omz plugin info | 主機能 | プラグインのREADME.mdを表示する処理を実行 |

## 機能種別

CLI / 情報表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| plugin | 文字列 | Yes | 情報を表示するプラグイン名 | プラグインディレクトリが存在すること |

### 入力データソース

- コマンドライン引数
- $ZSH/plugins/<plugin>/README.md
- $ZSH_CUSTOM/plugins/<plugin>/README.md

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| stdout | テキスト | README.mdの内容 |
| stderr | テキスト | エラーメッセージ |
| 戻り値 | 整数 | 0: 成功、1: エラー |

### 出力先

- 標準出力（README.md内容）
- 標準エラー出力（エラーメッセージ）

## 処理フロー

### 処理シーケンス

```
1. 引数チェック
   └─ プラグイン名が指定されているか確認
   └─ 未指定の場合はUsage表示してreturn 1

2. README.md検索
   └─ ZSH_CUSTOM/plugins/<plugin>/README.mdを検索
   └─ 見つからなければZSH/plugins/<plugin>/README.mdを検索

3. 出力先判定
   └─ パイプ出力の場合はcatで出力
   └─ ターミナル出力の場合はビューア選択

4. ビューア選択
   └─ glow利用可能: glowで表示
   └─ bat利用可能: batで表示
   └─ less利用可能: lessで表示
   └─ その他: catで表示

5. エラー処理
   └─ README.mdがない場合は専用エラー
   └─ プラグインが存在しない場合はエラー
```

### フローチャート

```mermaid
flowchart TD
    A[omz plugin info実行] --> B{引数あり?}
    B -->|No| C[Usage表示・return 1]
    B -->|Yes| D{ZSH_CUSTOM/plugins/plugin/README.md存在?}
    D -->|Yes| E[readmeパス設定]
    D -->|No| F{ZSH/plugins/plugin/README.md存在?}
    F -->|Yes| E
    F -->|No| G{プラグインディレクトリ存在?}
    G -->|Yes| H[README未存在エラー]
    G -->|No| I[プラグイン未検出エラー]
    E --> J{パイプ出力?}
    J -->|Yes| K[cat README.md]
    J -->|No| L{glow利用可能?}
    L -->|Yes| M[glow -p README.md]
    L -->|No| N{bat利用可能?}
    N -->|Yes| O[bat -l md README.md]
    N -->|No| P{less利用可能?}
    P -->|Yes| Q[less README.md]
    P -->|No| R[cat README.md]
    K --> S[完了]
    M --> S
    O --> S
    Q --> S
    R --> S
    H --> T[return 1]
    I --> T
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 引数必須 | プラグイン名の指定が必須 | 常時 |
| BR-02 | カスタムプラグイン優先 | ZSH_CUSTOMのREADME.mdを優先 | 同名プラグインが両方に存在する場合 |
| BR-03 | パイプ時はcat | 出力がパイプの場合はプレーンテキスト | パイプ使用時 |
| BR-04 | ビューア優先順位 | glow > bat > less > cat | ターミナル出力時 |
| BR-05 | README必須 | README.mdが存在しない場合はエラー | 常時 |

### 計算ロジック

**ターミナル判定**:
```zsh
[[ -t 1 ]]
```
- ファイルディスクリプタ1（stdout）がターミナルに接続されているか判定

**コマンド存在確認**:
```zsh
${+commands[glow]}
```
- commandsハッシュにglowが存在すれば1、なければ0

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 引数なしエラー | プラグイン名未指定 | Usage表示 |
| 1 | README未存在エラー | プラグインは存在するがREADME.mdがない | エラーメッセージ出力 |
| 1 | プラグイン未検出エラー | プラグイン自体が存在しない | エラーメッセージ出力 |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

特になし。ファイル読み込みと表示のみ。

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

- 読み取り専用の操作であり、システムへの影響はない
- glowやbat使用時はそれらのツールのセキュリティに依存

## 備考

- glowはMarkdown専用のCLIレンダラー（https://github.com/charmbracelet/glow）
- batはシンタックスハイライト付きのcatクローン（https://github.com/sharkdp/bat）
- パイプ出力時はプレーンテキストとして扱われる

---

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

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

### 推奨読解順序

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

プラグイン情報表示で扱う変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | readme変数、$commands配列 |

**読解のコツ**:
- `$ZSH_CUSTOM/plugins/<plugin>/README.md`が優先
- `$commands`はZSHのビルトインハッシュで、利用可能なコマンドを管理

#### Step 2: _omz::plugin::info関数を理解する

プラグイン情報表示のメイン処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | 418-454行目の_omz::plugin::info関数 |

**主要処理フロー**:
- **419-421行目**: 引数チェック
- **424-425行目**: README.mdパス検索（ZSH_CUSTOM優先）
- **426行目**: ファイル存在確認
- **428-431行目**: パイプ出力判定とcat実行
- **434-442行目**: ビューア選択とcase文
- **447-451行目**: エラー処理（READMEなし/プラグインなし）

#### Step 3: ビューア選択ロジックを理解する

ビューアの優先順位と選択ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | 437-442行目のcase文 |

**主要処理フロー**:
- **437行目**: `case 1 in` - 最初にマッチした条件を実行
- **438行目**: `${+commands[glow]}` - glow存在時
- **439行目**: `${+commands[bat]}` - bat存在時
- **440行目**: `${+commands[less]}` - less存在時
- **441行目**: `*` - その他（cat）

#### Step 4: エラー処理を理解する

エラーケースの判定と出力を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cli.zsh | `lib/cli.zsh` | 447-451行目のエラー処理 |

**主要処理フロー**:
- **447行目**: プラグインディレクトリ存在確認
- **448行目**: README未存在エラー
- **450行目**: プラグイン未検出エラー

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

```
omz plugin info <plugin>
    │
    └─ _omz::plugin::info()
           │
           ├─ 引数チェック
           │
           ├─ README.md検索
           │      ├─ $ZSH_CUSTOM/plugins/$1/README.md
           │      └─ $ZSH/plugins/$1/README.md
           │
           ├─ 出力先判定
           │      └─ [[ -t 1 ]] (ターミナル判定)
           │
           └─ ビューア選択
                  ├─ glow -p (Markdownレンダリング)
                  ├─ bat -l md --style plain (シンタックスハイライト)
                  ├─ less (ページャ)
                  └─ cat (プレーンテキスト)
```

### データフロー図

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

plugin名(引数)        ───▶ README.md検索
                              │
                              ├─▶ ZSH_CUSTOM/plugins/
                              │
                              └─▶ ZSH/plugins/
                                      │
                                      ▼
README.md             ───▶ ビューア選択
                              │
                              ├─▶ glow -p ──────────────────▶ リッチ表示
                              ├─▶ bat -l md ────────────────▶ ハイライト表示
                              ├─▶ less ─────────────────────▶ ページャ表示
                              └─▶ cat ──────────────────────▶ プレーン表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | _omz::plugin::info関数 |
| README.md | `plugins/*/README.md` | ドキュメント | プラグイン説明（公式） |
| README.md | `$ZSH_CUSTOM/plugins/*/README.md` | ドキュメント | プラグイン説明（カスタム） |
