# 機能設計書 25-ヘルプ表示（--help）

## 概要

本ドキュメントは、Prettier CLIにおける`--help`オプションの機能設計を記述する。このオプションは、CLIの使用方法とオプションの説明を表示する。

### 本機能の処理概要

**業務上の目的・背景**：CLIツールには、ユーザーが利用可能なオプションと使用方法を確認できる手段が必要である。本機能は、Prettierの全オプションを分類別に一覧表示し、各オプションの説明とデフォルト値を提供する。また、特定のオプションについて詳細な説明を表示することも可能である。

**機能の利用シーン**：
- Prettier初回利用時のオプション確認
- 特定オプションの詳細確認
- オプションのデフォルト値確認
- 利用可能なオプション一覧の確認

**主要な処理内容**：
1. ヘルプ引数の解析（全体ヘルプまたは特定オプション）
2. オプション情報の収集と整理
3. カテゴリ別のグループ化
4. ヘルプテキストの生成
5. 標準出力への表示

**関連システム・外部連携**：
- プラグインから提供されるオプション情報
- コアオプション定義

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 10 | Usage - Install | 補助機能 | インストール後のヘルプコマンドの使い方を説明 |
| 15 | Usage - CLI | 補助機能 | CLIでのヘルプ表示を説明 |

## 機能種別

情報表示 / ドキュメンテーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --help, -h | flag | No | ヘルプ表示の有効化 | - |
| [flag名] | string | No | 詳細を表示するオプション名 | 既存のオプション名 |

### 入力データソース

- CLIコマンドライン引数
- オプション定義（CLI固有、プラグイン提供）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 使用方法サマリー | string | 基本的な使用方法 |
| カテゴリ別オプション | string | カテゴリごとにグループ化されたオプション一覧 |

### 出力先

- 標準出力（テキスト形式）

**出力例**（一部抜粋）：
```
Usage: prettier [options] [file/dir/glob ...]

By default, output is written to stdout.
Stdin is read if it is piped to Prettier and no files are given.

Output options:

  -c, --check              Check if the given files are formatted, print a human-friendly summary
                           message and paths to unformatted files (see also --list-different).
  -l, --list-different     Print the names of files that are different from Prettier's formatting (see also --check).
  -w, --write              Edit files in-place. (Beware!)

...
```

## 処理フロー

### 処理シーケンス

```
1. ヘルプ引数の解析
   └─ --helpのみ：全体ヘルプ
   └─ --help <flag>：特定オプションの詳細

2. 全体ヘルプの場合
   └─ オプション一覧をカテゴリでグループ化
   └─ 各カテゴリ内でアルファベット順にソート
   └─ 使用方法サマリーとオプション一覧を結合

3. 詳細ヘルプの場合
   └─ 指定されたオプションを検索
   └─ ヘッダー、説明、選択肢、デフォルト値を構築

4. 出力
   └─ 標準出力に表示
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{--help引数}
    B -->|引数なし| C[全体ヘルプ生成]
    B -->|オプション名| D[詳細ヘルプ生成]
    C --> E[オプション収集]
    E --> F[カテゴリ別グループ化]
    F --> G[ソート]
    G --> H[テキスト構築]
    D --> I[オプション検索]
    I --> J[詳細情報構築]
    J --> H
    H --> K[標準出力]
    K --> L[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-25-1 | カテゴリ順序 | Output → Format → Config → Editor → Other の順で表示 | 全体ヘルプ |
| BR-25-2 | アルファベット順 | 各カテゴリ内のオプションはアルファベット順 | 全体ヘルプ |
| BR-25-3 | --no-オプション | oppositeDescriptionがある場合、--no-プレフィックス付きで表示 | 全体ヘルプ |
| BR-25-4 | デフォルト値表示 | デフォルト値がある場合は「Defaults to X」と表示 | 常時 |
| BR-25-5 | 選択肢表示 | choiceタイプの場合は有効な選択肢を一覧表示 | 詳細ヘルプ |

### 計算ロジック

**オプションヘッダー生成**：
```
header = [alias ? `-${alias},` : null, `--${name}`, type !== 'boolean' ? `<${type}>` : null].filter(Boolean).join(' ')
```

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

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

## エラー処理

### エラーケース一覧

特定のエラーケースは定義されていない（不明なオプション指定時の動作は未定義）。

### リトライ仕様

リトライは行わない。

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

トランザクション管理は不要。

## パフォーマンス要件

- オプション情報はコンテキスト初期化時に既に読み込まれているため、高速に表示可能

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

- ヘルプ情報のみを出力
- 機密情報の漏洩リスクはない

## 備考

- `-h`ショートエイリアスが利用可能
- 空文字列（`--help ""`）も許容される

---

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

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

### 推奨読解順序

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

ヘルプ生成に使用されるオプション情報の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | オプション定義の構造（type, description, choices等） |

**読解のコツ**: ファイル先頭のコメントにオプション定義の構造が詳細に記載されている。

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

CLIメイン処理からのヘルプ表示呼び出しを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/cli/index.js` | --helpの処理分岐 |

**主要処理フロー**:
- **74-81行目**: help引数の判定と分岐
- **76-77行目**: 引数の有無による分岐（詳細 vs 全体）

#### Step 3: ヘルプ生成ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | usage.js | `src/cli/usage.js` | createUsageとcreateDetailedUsage関数 |
| 3-2 | constants.evaluate.js | `src/cli/constants.evaluate.js` | カテゴリ順序とサマリーテンプレート |

**主要処理フロー（usage.js）**:
- **113-150行目**: createUsage関数（全体ヘルプ）
- **114-116行目**: オプションのアルファベット順ソート
- **118-126行目**: --no-オプションの除外処理
- **127行目**: カテゴリ別グループ化
- **129-138行目**: カテゴリ順序の適用
- **169-194行目**: createDetailedUsage関数（詳細ヘルプ）
- **177-184行目**: choice選択肢の表示

#### Step 4: ユーティリティ関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | usage.js | `src/cli/usage.js` | ヘルパー関数群 |

**主要処理フロー**:
- **39-44行目**: createOptionUsageHeader（オプションヘッダー生成）
- **57-69行目**: createOptionUsageType（型表示生成）
- **83-95行目**: createOptionUsage（オプション行生成）
- **97-111行目**: getOptionsWithOpposites（--no-オプション追加）

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

```
src/cli/index.js::main()
    │
    ├─ --help検出
    │
    └─ context.argv.help判定
           │
           ├─ 文字列（オプション名）の場合
           │      │
           │      └─ src/cli/usage.js::createDetailedUsage()
           │             ├─ getOptionsWithOpposites()
           │             ├─ オプション検索
           │             ├─ createOptionUsageHeader()
           │             └─ createChoiceUsages()
           │
           └─ 空文字列 or undefinedの場合
                  │
                  └─ src/cli/usage.js::createUsage()
                         ├─ オプションソート
                         ├─ getOptionsWithOpposites()
                         ├─ groupBy(category)
                         └─ createOptionUsage()
```

### データフロー図

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

--help ────────────────▶ 引数解析 ───────────────────────▶ ヘルプタイプ判定
                               │
                               ▼
context.detailedOptions ──▶ オプション収集 ─────────────▶ オプション配列
                               │
                               ▼
categoryOrder ───────────▶ カテゴリグループ化 ──────────▶ グループ化配列
                               │
                               ▼
                         テキスト構築 ──────────────────▶ ヘルプ文字列
                               │
                               ▼
                         printToScreen ─────────────────▶ 標準出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| usage.js | `src/cli/usage.js` | ソース | ヘルプ生成ロジック |
| cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ソース | オプション定義 |
| constants.evaluate.js | `src/cli/constants.evaluate.js` | ソース | カテゴリ順序、サマリー |
| index.js | `src/cli/index.js` | ソース | CLIエントリーポイント |
| context.js | `src/cli/context.js` | ソース | コンテキスト（detailedOptions保持） |
| utilities.js | `src/cli/utilities.js` | ソース | groupBy等ユーティリティ |
