# 機能設計書 28-サポート情報取得（getSupportInfo）

## 概要

本ドキュメントは、Prettier APIにおける`getSupportInfo`関数の機能設計を記述する。この関数は、対応言語、パーサー、オプションの情報を取得する。

### 本機能の処理概要

**業務上の目的・背景**：Prettierがサポートする言語やオプションは、ビルトインプラグインや外部プラグインによって動的に拡張される。エディタ統合やツール開発者は、現在利用可能な言語・オプション情報をプログラマティックに取得する必要がある。本機能は、この情報をAPIとして提供する。

**機能の利用シーン**：
- エディタプラグインでのオプションUI動的生成
- Playgroundでの言語・オプション選択肢生成
- ドキュメント自動生成
- 互換性チェックツール

**主要な処理内容**：
1. プラグインからの言語情報収集
2. コアオプションとプラグインオプションのマージ
3. パーサー選択肢の動的生成
4. プラグインデフォルト値の収集
5. 結果オブジェクトの構築

**関連システム・外部連携**：
- プラグインシステム（ビルトイン・外部）
- コアオプション定義

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | ホームページ | API連携 | 対応言語・エディタ一覧の表示データを取得 |
| 2 | Playground | API連携 | 利用可能なオプション情報を取得してサイドバーに表示 |
| 16 | Usage - API | 補助機能 | APIでのgetSupportInfo関数の使い方を説明 |

## 機能種別

情報取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| options | object | No | オプションオブジェクト | - |
| options.plugins | (string \| object)[] | No | 使用するプラグイン | パスまたはプラグインオブジェクトの配列 |
| options.showDeprecated | boolean | No | 非推奨オプションを含めるか | デフォルト: false |

### 入力データソース

- 関数引数
- ビルトインプラグイン
- 外部プラグイン

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| languages | SupportLanguage[] | サポートされる言語の配列 |
| options | NamedOptionInfo[] | 利用可能なオプションの配列 |

### SupportLanguage構造

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | string | 言語名 |
| parsers | string[] | 対応パーサーのリスト |
| extensions | string[] | 対応ファイル拡張子 |
| filenames | string[] | 対応ファイル名 |
| interpreters | string[] | 対応インタープリタ |
| aliases | string[] | 言語エイリアス |

### NamedOptionInfo構造

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | string | オプション名 |
| type | string | 値の型（boolean, int, string, choice等） |
| default | any | デフォルト値 |
| description | string | 説明 |
| choices | array | 選択肢（typeがchoiceの場合） |
| pluginDefaults | object | プラグインごとのデフォルト値 |

### 出力先

- 戻り値（Promise<{ languages, options }>）

## 処理フロー

### 処理シーケンス

```
1. プラグインの読み込み
   └─ withPluginsラッパーでビルトイン・外部プラグインを統合

2. 言語情報の収集
   └─ 各プラグインのlanguages配列をフラット化

3. オプション情報の構築
   └─ プラグインオプションとコアオプションをマージ
   └─ normalizeOptionSettingsで正規化

4. 非推奨オプションのフィルタリング
   └─ showDeprecatedがfalseの場合は除外

5. パーサー選択肢の拡張
   └─ languages内のparsersからパーサー選択肢を追加

6. プラグインデフォルト値の収集
   └─ 各プラグインのdefaultOptionsをpluginDefaultsに格納

7. 結果構築
   └─ { languages, options }オブジェクトを返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[プラグイン読み込み]
    B --> C[言語情報収集]
    C --> D[オプション情報構築]
    D --> E{showDeprecated?}
    E -->|No| F[非推奨を除外]
    E -->|Yes| G[非推奨を含む]
    F --> H[パーサー選択肢拡張]
    G --> H
    H --> I[pluginDefaults収集]
    I --> J[結果構築]
    J --> K[Promise<{ languages, options }>]
    K --> L[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-28-1 | 非推奨除外 | showDeprecatedがfalseの場合、deprecatedオプション/選択肢を除外 | デフォルト |
| BR-28-2 | パーサー動的追加 | parserオプションの選択肢は言語定義から動的に追加 | 常時 |
| BR-28-3 | プラグインデフォルト | 各プラグインのdefaultOptionsをpluginDefaultsに収集 | 常時 |
| BR-28-4 | オプションマージ | プラグインオプションはコアオプションより優先（後勝ち） | 常時 |
| BR-28-5 | default配列処理 | defaultが配列の場合、最後の要素のvalueを使用 | オプション正規化時 |

### 計算ロジック

**オプションマージ**：
```javascript
Object.assign({}, ...plugins.map(({ options }) => options), coreOptions)
```

**パーサー選択肢追加**：
```javascript
collectParsersFromLanguages(parserChoices, languages, plugins)
// 言語からパーサー名を収集し、既存の選択肢にないものを追加
```

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

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

## エラー処理

### エラーケース一覧

特定のエラーケースは定義されていない。

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

- プラグイン読み込みを含むため、初回実行時は若干の遅延がありうる
- 結果はキャッシュされない

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

- 言語・オプション情報のみを返す
- 機密情報の漏洩リスクはない

## 備考

- CLIの`--support-info`オプションはこの関数を内部で使用
- Playgroundでのオプション表示に使用されている

---

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

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

### 推奨読解順序

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

SupportLanguageとNamedOptionInfoの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | support.js | `src/main/support.js` | JSDocコメントで定義されている型 |
| 1-2 | core-options.evaluate.js | `src/main/core-options.evaluate.js` | コアオプションの定義 |

**読解のコツ**: `NamedOptionInfo`は`name`プロパティが追加された`OptionInfo`である。

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

API公開の流れを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/index.js` | withPluginsラッパーとエクスポート |

**主要処理フロー**:
- **87行目**: withPluginsでラップ（optionsArgumentIndex=0）
- **135行目**: getSupportInfoのエクスポート

#### Step 3: 本体実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | support.js | `src/main/support.js` | getSupportInfo関数の実装 |

**主要処理フロー**:
- **16-17行目**: 言語情報の収集
- **19-47行目**: オプション情報の構築ループ
- **20-22行目**: オプションのマージと正規化
- **23-25行目**: 非推奨オプションの除外
- **27-29行目**: 非推奨選択肢の除外
- **32-37行目**: parserオプションの選択肢拡張
- **40-44行目**: pluginDefaultsの収集
- **49行目**: 結果オブジェクトの返却

#### Step 4: パーサー収集ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | support.js | `src/main/support.js` | collectParsersFromLanguages関数 |

**主要処理フロー**:
- **52-74行目**: 言語からパーサーを収集
- **53行目**: 既存パーサーのSet作成
- **55-73行目**: 各言語のparsersをイテレート
- **60-63行目**: プラグイン名を説明に追加

#### Step 5: オプション正規化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | support.js | `src/main/support.js` | normalizeOptionSettings関数 |

**主要処理フロー**:
- **76-90行目**: オプションの正規化
- **79行目**: nameプロパティの追加
- **82-84行目**: default配列の処理

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

```
src/index.js::getSupportInfo()
    │
    └─ withPlugins() [optionsArgumentIndex=0]
           │
           ├─ loadBuiltinPlugins()
           │
           ├─ loadPlugins()
           │
           └─ src/main/support.js::getSupportInfo()
                  │
                  ├─ plugins.flatMap(p => p.languages) - 言語収集
                  │
                  ├─ Object.assign(...options, coreOptions) - オプションマージ
                  │
                  ├─ normalizeOptionSettings() - 正規化
                  │
                  ├─ collectParsersFromLanguages() - パーサー収集
                  │
                  └─ pluginDefaults収集
```

### データフロー図

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

options.plugins ────────▶ withPlugins ─────────────────▶ 統合プラグイン配列
                               │
                               ▼
各プラグイン.languages ────▶ flatMap ──────────────────▶ languages配列
                               │
                               ▼
各プラグイン.options ──────▶ Object.assign ────────────▶ マージされたオプション
coreOptions ────────────────▶│
                               ▼
                         normalizeOptionSettings ──────▶ 正規化されたオプション
                               │
                               ▼
options.showDeprecated ────▶ フィルタリング ────────────▶ フィルタ済みオプション
                               │
                               ▼
languages ───────────────▶ collectParsersFromLanguages ▶ parser選択肢拡張
                               │
                               ▼
各プラグイン.defaultOptions ▶ pluginDefaults収集 ───────▶ 最終オプション配列
                               │
                               ▼
                         結果構築 ─────────────────────▶ { languages, options }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| support.js | `src/main/support.js` | ソース | メイン実装 |
| index.js | `src/index.js` | ソース | API公開エントリーポイント |
| core-options.evaluate.js | `src/main/core-options.evaluate.js` | ソース | コアオプション定義 |
| load-plugins.js | `src/main/plugins/load-plugins.js` | ソース | プラグイン読み込み |
| load-builtin-plugins.js | `src/main/plugins/load-builtin-plugins.js` | ソース | ビルトインプラグイン読み込み |
