# 帳票設計書 2-サポート情報

## 概要

本ドキュメントは、Prettierがサポートする言語・オプション一覧をJSON形式で出力する帳票「サポート情報」の設計仕様を定義する。

### 本帳票の処理概要

**業務上の目的・背景**：Prettierは多数のプログラミング言語とフォーマットオプションをサポートしており、これらの情報をプログラムから取得できることが重要である。エディタプラグインやIDE統合、CI/CDツールとの連携において、サポートされている言語やオプションの一覧を動的に取得し、適切なパーサーやオプションを選択するために本帳票が使用される。また、開発者がPrettierの機能を把握する際のリファレンスとしても活用される。

**帳票の利用シーン**：エディタプラグイン開発時のサポート言語確認、プロジェクト設定ツールでの利用可能オプションの提示、CLIラッパーツールでのオプション検証、Prettier自体の機能確認など。

**主要な出力内容**：
1. サポート言語一覧（言語名、パーサー、拡張子、ファイル名パターン等）
2. フォーマットオプション一覧（オプション名、型、デフォルト値、選択肢等）

**帳票の出力タイミング**：CLIで`--support-info`オプションを指定した際、またはAPI経由で`getSupportInfo()`関数を呼び出した際に出力される。

**帳票の利用者**：エディタプラグイン開発者、IDE統合開発者、CI/CDツール開発者、Prettierユーザー

## 帳票種別

情報出力（JSON）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| CLI-01 | コマンドライン | `prettier --support-info` | コマンド実行 |
| API-01 | JavaScript API | `prettier.getSupportInfo(options)` | 関数呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON |
| 出力先 | 標準出力 |
| 文字コード | UTF-8 |
| フォーマット | 整形済みJSON（Prettierでフォーマット） |

### JSON構造

```json
{
  "languages": [
    {
      "name": "言語名",
      "parsers": ["パーサー名"],
      "extensions": [".拡張子"],
      "filenames": ["ファイル名"],
      ...
    }
  ],
  "options": [
    {
      "name": "オプション名",
      "type": "型",
      "default": "デフォルト値",
      "description": "説明",
      ...
    }
  ]
}
```

## 帳票レイアウト

### レイアウト概要

出力は2つの主要セクション（languages, options）で構成されるJSONオブジェクト。

```
┌─────────────────────────────────────┐
│              JSONオブジェクト          │
├─────────────────────────────────────┤
│  "languages": [                      │
│    { 言語情報オブジェクト },            │
│    ...                               │
│  ],                                  │
│  "options": [                        │
│    { オプション情報オブジェクト },        │
│    ...                               │
│  ]                                   │
└─────────────────────────────────────┘
```

### languages配列の項目

| No | 項目名 | 説明 | 型 | 備考 |
|----|-------|------|-----|------|
| 1 | name | 言語名 | string | 表示用の名前 |
| 2 | parsers | パーサー名一覧 | string[] | 使用可能なパーサー |
| 3 | extensions | ファイル拡張子 | string[] | 対応する拡張子 |
| 4 | filenames | 特定ファイル名 | string[] | 拡張子ではなく名前で判定 |
| 5 | linguistLanguageId | Linguist言語ID | number | GitHub Linguist対応 |
| 6 | vscodeLanguageIds | VSCode言語ID | string[] | VSCode統合用 |

### options配列の項目

| No | 項目名 | 説明 | 型 | 備考 |
|----|-------|------|-----|------|
| 1 | name | オプション名 | string | camelCase形式 |
| 2 | type | 値の型 | string | boolean/int/string/choice/path |
| 3 | default | デフォルト値 | any | 型に応じた値 |
| 4 | description | 説明 | string | オプションの説明文 |
| 5 | choices | 選択肢 | object[] | type=choice時のみ |
| 6 | range | 値の範囲 | object | start/end/step |
| 7 | category | カテゴリ | string | 分類（Format, Config等） |
| 8 | deprecated | 非推奨フラグ | boolean/string | 非推奨の場合の代替案 |
| 9 | pluginDefaults | プラグインデフォルト | object | プラグイン毎のデフォルト値 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| プラグイン | 読み込むプラグイン一覧 | No |
| showDeprecated | 非推奨項目の表示 | No（デフォルト: false） |

### フィルタリング

| 対象 | 条件 | 処理 |
|------|------|------|
| options | deprecated=true & showDeprecated=false | 除外 |
| choices | deprecated=true & showDeprecated=false | 除外 |
| options | cliName, cliCategory, cliDescription | 出力から除外 |

## データフロー仕様

### 入力データ

| データ項目 | 型 | 説明 |
|-----------|-----|------|
| options.plugins | array | 追加プラグイン（文字列またはオブジェクト） |
| options.showDeprecated | boolean | 非推奨項目表示フラグ |

### 出力データ

| データ項目 | 型 | 説明 |
|-----------|-----|------|
| languages | array | サポート言語一覧 |
| options | array | フォーマットオプション一覧 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[--support-info実行] --> B[printSupportInfo呼び出し]
    B --> C[getSupportInfo呼び出し]
    C --> D[プラグイン読み込み]
    D --> E[言語情報収集]
    E --> F[オプション情報収集]
    F --> G[名前でソート]
    G --> H[CLI専用項目除外]
    H --> I[JSON文字列化]
    I --> J[Prettierでフォーマット]
    J --> K[標準出力]
```

### データ収集フロー

```mermaid
flowchart TD
    A[getSupportInfo] --> B{プラグイン指定?}
    B -->|Yes| C[loadPlugins]
    B -->|No| D[loadBuiltinPlugins]
    C --> E[プラグインからlanguages収集]
    D --> E
    E --> F[プラグインからoptions収集]
    F --> G[coreOptionsとマージ]
    G --> H[normalizeOptionSettings]
    H --> I[パーサー選択肢追加]
    I --> J[pluginDefaults設定]
    J --> K[結果返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| プラグイン読み込みエラー | 指定プラグインが見つからない | Module not found | プラグインパスを確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 処理方式 | 非同期処理（async/await） |
| キャッシュ | プラグイン読み込み結果をキャッシュ |
| 出力サイズ | 数KB〜数十KB（プラグイン数に依存） |

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

- プラグイン情報のみを出力し、ファイルシステムへのアクセスは行わない
- プラグインは信頼できるソースから読み込む

## 備考

- 出力は`fast-json-stable-stringify`で安定した順序を保証
- 最終出力はPrettierのJSONパーサーでフォーマット
- showDeprecatedオプションでAPI使用時のみ非推奨項目を表示可能

---

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

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

### 推奨読解順序

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

まず、サポート情報の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | support.js | `src/main/support.js` | getSupportInfo関数の戻り値構造（16-50行目） |
| 1-2 | core-options.evaluate.js | `src/main/core-options.evaluate.js` | コアオプションの定義 |

**読解のコツ**: languagesはプラグインから収集され、optionsはプラグインオプションとコアオプションがマージされる。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/cli/index.js` | context.argv.supportInfo判定（83-85行目） |
| 2-2 | print-support-info.js | `src/cli/print-support-info.js` | printSupportInfo関数全体（8-20行目） |

**主要処理フロー**:
1. **83-85行目**: supportInfoオプションの判定とprintSupportInfo呼び出し
2. **9行目**: getSupportInfoで情報取得
3. **17行目**: Prettierでフォーマット
4. **19行目**: 標準出力へ出力

#### Step 3: サポート情報収集処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | support.js | `src/main/support.js` | getSupportInfo関数（16-50行目） |
| 3-2 | support.js | `src/main/support.js` | normalizeOptionSettings関数（76-90行目） |
| 3-3 | support.js | `src/main/support.js` | collectParsersFromLanguages関数（52-74行目） |

**主要処理フロー**:
- **17行目**: プラグインからlanguages収集
- **19-47行目**: オプション情報の収集と加工
- **32-37行目**: パーサー選択肢の動的追加
- **40-44行目**: pluginDefaultsの設定

#### Step 4: 出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | print-support-info.js | `src/cli/print-support-info.js` | 出力フォーマット処理（10-19行目） |
| 4-2 | utilities.js | `src/cli/utilities.js` | omit関数による項目除外（109行目） |

**主要処理フロー**:
- **10-11行目**: 言語とオプションをソート
- **12-14行目**: CLI専用項目（cliName, cliCategory, cliDescription）を除外
- **17行目**: JSONパーサーでフォーマット

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

```
CLI: main() [src/cli/index.js:39]
    │
    └─ printSupportInfo() [src/cli/print-support-info.js:8]
           │
           ├─ getSupportInfo() [src/index.js:87]
           │      │
           │      └─ withPlugins() [src/index.js:43]
           │             │
           │             ├─ loadBuiltinPlugins() [src/main/plugins/index.js]
           │             │
           │             └─ getSupportInfoWithoutPlugins() [src/main/support.js:16]
           │                    │
           │                    ├─ normalizeOptionSettings() [src/main/support.js:76]
           │                    │
           │                    └─ collectParsersFromLanguages() [src/main/support.js:52]
           │
           ├─ stringify() [fast-json-stable-stringify]
           │
           ├─ format() [src/index.js:68]
           │
           └─ printToScreen() [src/cli/utilities.js:8]
```

### データフロー図

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

plugins配列 ──────────▶ loadPlugins() ──────────▶ プラグインオブジェクト
                              │
                              ▼
                     plugin.languages収集
                              │
                              ▼
                     plugin.options収集
                              │
                              ▼
                     coreOptionsマージ
                              │
                              ▼
                     normalizeOptionSettings()
                              │
                              ▼
                        sortByName()
                              │
                              ▼
                          omit()
                              │
                              ▼
                     stringify() + format()
                              │
                              ▼
{ languages, options } ◀──────────────────────▶ 整形済みJSON出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| print-support-info.js | `src/cli/print-support-info.js` | ソース | CLI用サポート情報出力 |
| support.js | `src/main/support.js` | ソース | サポート情報収集ロジック |
| index.js | `src/index.js` | ソース | getSupportInfo API公開 |
| core-options.evaluate.js | `src/main/core-options.evaluate.js` | ソース | コアオプション定義 |
| utilities.js | `src/cli/utilities.js` | ソース | omit, printToScreen関数 |
| index.js | `src/main/plugins/index.js` | ソース | プラグイン読み込み |
