# 帳票設計書 4-ヘルプ・使用方法

## 概要

本ドキュメントは、CLIのヘルプメッセージをテキスト形式で出力する帳票「ヘルプ・使用方法」の設計仕様を定義する。

### 本帳票の処理概要

**業務上の目的・背景**：コマンドラインツールにおいて、ユーザーが利用可能なオプションや使用方法を確認できることは基本的な要件である。本帳票は、Prettierの全オプションとその説明、デフォルト値を整理して表示し、ユーザーが適切なオプションを選択してコマンドを実行できるようサポートする。また、特定のオプションについて詳細な説明を確認する機能も提供する。

**帳票の利用シーン**：Prettier初回利用時のオプション確認、特定オプションの詳細確認、CI/CDスクリプト作成時のオプション参照、トラブルシューティング時の設定確認など。

**主要な出力内容**：
1. 使用方法サマリー
2. カテゴリ別オプション一覧（Output, Format, Config, Editor, Other）
3. 各オプションの説明とデフォルト値

**帳票の出力タイミング**：CLIで`--help`オプションを指定した際、または引数なしで実行した際に出力される。`--help <option>`で特定オプションの詳細表示も可能。

**帳票の利用者**：Prettierを使用する全ての開発者、DevOpsエンジニア

## 帳票種別

テキスト出力

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| CLI-01 | コマンドライン | `prettier --help` | コマンド実行 |
| CLI-02 | コマンドライン | `prettier --help <option>` | コマンド実行 |
| CLI-03 | コマンドライン | `prettier`（引数なし） | コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト |
| 出力先 | 標準出力 |
| 文字コード | UTF-8 |
| フォーマット | インデント付きテキスト |

### レイアウト構成

```
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:

  --check                 Check if files are formatted.
  --list-different        List files that differ from Prettier's formatting.
  ...

Format options:
  ...

Config options:
  ...

Editor options:
  ...

Other options:
  ...
```

## 帳票レイアウト

### レイアウト概要

出力は使用方法サマリーとカテゴリ別オプション一覧で構成される。

```
┌─────────────────────────────────────┐
│           使用方法サマリー            │
├─────────────────────────────────────┤
│  Output options:                     │
│    --option1    説明                 │
│    --option2    説明                 │
├─────────────────────────────────────┤
│  Format options:                     │
│    --option3    説明                 │
│    ...                               │
├─────────────────────────────────────┤
│  Config options:                     │
│    ...                               │
├─────────────────────────────────────┤
│  Editor options:                     │
│    ...                               │
├─────────────────────────────────────┤
│  Other options:                      │
│    ...                               │
└─────────────────────────────────────┘
```

### サマリー部

| No | 項目名 | 説明 | 表示形式 |
|----|-------|------|---------|
| 1 | Usage | コマンド使用方法 | `prettier [options] [file/dir/glob ...]` |
| 2 | 説明 | デフォルト動作の説明 | テキスト |

### オプション一覧部

| No | 項目名 | 説明 | 表示形式 |
|----|-------|------|---------|
| 1 | オプション名 | `--{name}` 形式 | 左寄せ |
| 2 | エイリアス | `-{alias}` 形式（存在時） | オプション名の前 |
| 3 | 型指定 | `<type>` 形式 | オプション名の後 |
| 4 | 説明 | オプションの説明文 | 25文字目以降 |
| 5 | デフォルト値 | `Defaults to {value}.` | 説明の後 |

### 詳細ヘルプ形式（--help <option>）

| No | 項目名 | 説明 | 表示形式 |
|----|-------|------|---------|
| 1 | ヘッダー | オプション名と型 | `--option <type>` |
| 2 | 説明 | オプションの詳細説明 | 2スペースインデント |
| 3 | 選択肢 | type=choice時の選択肢 | `Valid options:` セクション |
| 4 | デフォルト値 | `Default: {value}` | |
| 5 | プラグインデフォルト | プラグイン毎のデフォルト | `Plugin defaults:` セクション |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| プラグイン | 読み込むプラグイン一覧 | No |
| help引数 | 詳細表示するオプション名 | No |

### フィルタリング

| 対象 | 条件 | 処理 |
|------|------|------|
| オプション | type=boolean & oppositeDescriptionあり & 名前がno-で始まらない | 除外 |
| オプション | descriptionなし | 除外 |

## データフロー仕様

### 入力データ

| データ項目 | 型 | 説明 |
|-----------|-----|------|
| context.argv.help | boolean \| string | ヘルプフラグまたはオプション名 |
| context.detailedOptions | array | 詳細オプション情報 |

### 出力データ

| データ項目 | 型 | 説明 |
|-----------|-----|------|
| usage | string | 整形されたヘルプテキスト |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[--help実行] --> B{引数あり?}
    B -->|No| C[createUsage呼び出し]
    B -->|Yes| D[createDetailedUsage呼び出し]
    C --> E[オプションソート]
    E --> F[getOptionsWithOpposites]
    F --> G[カテゴリでグループ化]
    G --> H[カテゴリ毎に出力整形]
    H --> I[usageSummaryと結合]
    D --> J[指定オプション検索]
    J --> K[ヘッダー生成]
    K --> L[説明追加]
    L --> M{type=choice?}
    M -->|Yes| N[選択肢追加]
    M -->|No| O[デフォルト値追加]
    N --> O
    O --> P[pluginDefaults追加]
    I --> Q[printToScreen]
    P --> Q
```

### オプション整形フロー

```mermaid
flowchart TD
    A[createOptionUsage] --> B[createOptionUsageHeader]
    B --> C{エイリアスあり?}
    C -->|Yes| D[-alias追加]
    C -->|No| E[--name追加]
    D --> E
    E --> F{type判定}
    F -->|boolean| G[型なし]
    F -->|choice| H[<value1|value2|...>]
    F -->|other| I[<type>]
    G --> J[createOptionUsageRow]
    H --> J
    I --> J
    J --> K[説明追加]
    K --> L[デフォルト値追加]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 該当なし | 存在しないオプション指定 | undefined参照エラー | 正しいオプション名を指定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 処理方式 | 同期処理 |
| 出力サイズ | 数KB |

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

- 静的なテキスト出力のみで、セキュリティリスクはない

## 備考

- カテゴリ順序は`categoryOrder`で定義（Output, Format, Config, Editor, Other）
- オプション閾値（OPTION_USAGE_THRESHOLD）は25文字
- 選択肢のマージン（CHOICE_USAGE_MARGIN）は3文字
- 選択肢のインデント（CHOICE_USAGE_INDENTATION）は2スペース

---

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

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

### 推奨読解順序

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

まず、オプション情報の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | constants.evaluate.js | `src/cli/constants.evaluate.js` | usageSummaryとcategoryOrder定義（4-17行目） |

**読解のコツ**: categoryOrderでカテゴリの表示順序が決まる。optionCategoriesはprettier-internal.jsから取得。

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

CLIからの処理起点を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/cli/index.js` | context.argv.help判定（74-81行目） |

**主要処理フロー**:
1. **74行目**: helpオプションの存在チェック
2. **76-78行目**: 引数があればcreateDetailedUsage、なければcreateUsage呼び出し
3. **79行目**: printToScreenで出力

#### Step 3: ヘルプ生成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | usage.js | `src/cli/usage.js` | createUsage関数（113-150行目） |
| 3-2 | usage.js | `src/cli/usage.js` | createDetailedUsage関数（169-194行目） |
| 3-3 | usage.js | `src/cli/usage.js` | getOptionsWithOpposites関数（97-111行目） |

**主要処理フロー**:
- **114-116行目**: オプションを名前でソート
- **118-126行目**: 不要なオプションをフィルタ
- **127行目**: カテゴリでグループ化
- **140-146行目**: カテゴリ毎にオプション一覧を生成
- **149行目**: usageSummaryと結合

#### Step 4: オプション整形処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | usage.js | `src/cli/usage.js` | createOptionUsage関数（83-95行目） |
| 4-2 | usage.js | `src/cli/usage.js` | createOptionUsageHeader関数（39-44行目） |
| 4-3 | usage.js | `src/cli/usage.js` | createOptionUsageType関数（57-69行目） |
| 4-4 | usage.js | `src/cli/usage.js` | createOptionUsageRow関数（46-55行目） |

**主要処理フロー**:
- **39-44行目**: エイリアス、名前、型を結合してヘッダー生成
- **57-69行目**: 型に応じた表示形式を決定
- **46-55行目**: 閾値に基づいて説明を整形

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

```
CLI: main() [src/cli/index.js:39]
    │
    ├─ createUsage() [src/cli/usage.js:113]
    │      │
    │      ├─ detailedOptions.sort()
    │      │
    │      ├─ getOptionsWithOpposites() [src/cli/usage.js:97]
    │      │
    │      ├─ groupBy() [src/cli/utilities.js:17]
    │      │
    │      └─ createOptionUsage() [src/cli/usage.js:83]
    │             │
    │             ├─ createOptionUsageHeader() [src/cli/usage.js:39]
    │             │      │
    │             │      └─ createOptionUsageType() [src/cli/usage.js:57]
    │             │
    │             ├─ getOptionDefaultValue() [src/cli/usage.js:20]
    │             │
    │             └─ createOptionUsageRow() [src/cli/usage.js:46]
    │
    └─ createDetailedUsage() [src/cli/usage.js:169]
           │
           ├─ getOptionsWithOpposites() [src/cli/usage.js:97]
           │
           ├─ createOptionUsageHeader() [src/cli/usage.js:39]
           │
           ├─ createChoiceUsages() [src/cli/usage.js:71]
           │
           ├─ getOptionDefaultValue() [src/cli/usage.js:20]
           │
           └─ createPluginDefaults() [src/cli/usage.js:152]
```

### データフロー図

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

context.argv.help ────▶ 引数判定 ─────────────────▶ 処理分岐
                              │
                              ├─ (引数なし)
                              │      │
                              │      ▼
                              │  createUsage()
                              │      │
                              │      ▼
                              │  オプションソート
                              │      │
                              │      ▼
                              │  カテゴリグループ化
                              │      │
                              │      ▼
                              │  整形済みテキスト
                              │
                              └─ (引数あり)
                                     │
                                     ▼
                              createDetailedUsage()
                                     │
                                     ▼
                              詳細整形テキスト
                                     │
                                     ▼
                              printToScreen() ──────▶ 標準出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| usage.js | `src/cli/usage.js` | ソース | ヘルプテキスト生成 |
| constants.evaluate.js | `src/cli/constants.evaluate.js` | ソース | 定数定義（usageSummary, categoryOrder） |
| index.js | `src/cli/index.js` | ソース | CLIエントリーポイント |
| utilities.js | `src/cli/utilities.js` | ソース | groupBy, printToScreen関数 |
| prettier-internal.js | `src/cli/prettier-internal.js` | ソース | optionCategories取得 |
