# 機能設計書 32-ビルトインプラグイン管理

## 概要

本ドキュメントは、Prettierのビルトインプラグイン管理機能について記述する。この機能は、Prettierに組み込まれた言語サポートのプラグインを管理し、遅延読み込みによるパフォーマンス最適化を実現する。

### 本機能の処理概要

ビルトインプラグイン管理は、JavaScript、TypeScript、CSS、HTML、Markdown、YAML、GraphQL、JSON等のPrettier標準対応言語のプラグインを管理する機能である。本番環境と開発環境で異なるプラグイン構成を使用し、遅延読み込み（Lazy Loading）によりパフォーマンスを最適化している。

**業務上の目的・背景**：Prettierは多数の言語をサポートしているが、すべてのプラグインを起動時に読み込むとパフォーマンスに影響する。ビルトインプラグイン管理では、必要な時にのみプラグインを読み込む遅延読み込み機構を提供し、初期化時間の短縮とメモリ使用量の削減を実現している。また、本番環境と開発環境で異なるプラグイン構成を使用することで、開発時のデバッグ効率と本番時のパフォーマンスを両立している。

**機能の利用シーン**：
- Prettier APIを呼び出してコードをフォーマットする際に、内部で自動的に呼び出される
- CLIでPrettierを実行する際に、対象ファイルの言語に応じたプラグインが読み込まれる
- エディタ統合でリアルタイムフォーマットを実行する際

**主要な処理内容**：
1. 環境（本番/開発）に応じたプラグインリストの選択
2. プラグイン情報の遅延読み込みラッパーの生成
3. パーサー/プリンターの遅延初期化
4. プラグインオプションと言語情報の即時提供

**関連システム・外部連携**：Prettierコア、各言語パーサー（Babel、TypeScript、PostCSS等）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | Usage - Plugins | 主画面 | 組み込みプラグインの仕組みを説明 |
| 5 | About - Prettier概要 | 参照画面 | 対応言語としてビルトインプラグインを説明 |

## 機能種別

プラグイン管理 / 遅延読み込み最適化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | 本機能は内部的に呼び出され、外部からの入力パラメータはなし | - |

### 入力データソース

- 環境変数 `NODE_ENV` による本番/開発環境の判定
- ビルドスクリプトによる自動生成プラグインリスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| plugins | Array<Plugin> | 遅延読み込みラッパーを持つビルトインプラグインの配列 |

### 出力先

Prettier内部のプラグインレジストリ（formatWithCursor等のAPI内部で使用）

## 処理フロー

### 処理シーケンス

```
1. loadBuiltinPlugins関数呼び出し
   └─ キャッシュの確認
2. 環境に応じたプラグインリストの読み込み
   ├─ 本番環境 → production-plugins.js
   └─ 開発環境 → development-plugins.js
3. toLazyLoadPlugins関数でプラグイン配列を変換
   └─ 各プラグインにtolodyLoadPluginを適用
4. toLazyLoadPlugin関数で遅延読み込みラッパーを生成
   ├─ options → 即時設定
   ├─ languages → 即時設定
   ├─ parsers → 遅延読み込み関数として設定
   └─ printers → 遅延読み込み関数として設定
5. 変換済みプラグイン配列を返却
```

### フローチャート

```mermaid
flowchart TD
    A[loadBuiltinPlugins呼び出し] --> B{キャッシュあり?}
    B -->|Yes| C[キャッシュから返却]
    B -->|No| D{NODE_ENV === production?}
    D -->|Yes| E[production-plugins.jsを読み込み]
    D -->|No| F[development-plugins.jsを読み込み]
    E --> G[toLazyLoadPlugins実行]
    F --> G
    G --> H[各プラグインにtolodyLoadPluginを適用]
    H --> I[options/languagesを即時設定]
    I --> J[parsers/printersを遅延読み込み関数化]
    J --> K[キャッシュに保存]
    K --> L[プラグイン配列を返却]
    C --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-32-01 | 環境別プラグイン | 本番と開発で異なるプラグイン構成を使用 | NODE_ENV環境変数による判定 |
| BR-32-02 | 遅延読み込み | パーサー/プリンターは初回使用時にのみ読み込み | パーサー/プリンター呼び出し時 |
| BR-32-03 | キャッシュ利用 | 一度読み込んだプラグインリストはキャッシュ | loadBuiltinPlugins再呼び出し時 |
| BR-32-04 | 即時設定情報 | options/languagesはプラグイン変換時に即時設定 | プラグイン情報参照時 |

### 計算ロジック

特になし

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

### 操作別データベース影響一覧

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ImportError | プラグインモジュールの読み込みに失敗した場合 | ビルドの再実行、依存関係の確認 |

### リトライ仕様

リトライは行わない。

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

本機能はトランザクション管理を必要としない。

## パフォーマンス要件

- 遅延読み込みにより初期化時間を短縮
- キャッシュ機構によりプラグインリストの再生成を回避
- 本番環境では最適化されたプラグイン構成を使用

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

- ビルトインプラグインはPrettierパッケージに含まれるため、外部からの改ざんリスクは低い
- ビルドスクリプトによる自動生成のため、プラグインリストの整合性が保証される

## 備考

- プラグインリストは `scripts/generate-builtin-plugins.js` で自動生成される
- 開発環境ではより詳細なデバッグ情報が利用可能
- 本番環境ではバンドルサイズの最適化が適用される

---

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

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

### 推奨読解順序

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

プラグイン情報の型定義と構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | utilities.js | `src/main/plugins/builtin-plugins/utilities.js` | PluginInformation型定義（1-10行目）でプラグイン情報の構造を理解 |

**読解のコツ**: PluginInformationは`name`（プラグイン名）、`load`（遅延読み込み関数）、`options`（オプション定義）、`languages`（対応言語）、`parsers`（パーサー名配列）、`printers`（プリンター名配列）を持つ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | load-builtin-plugins.js | `src/main/plugins/load-builtin-plugins.js` | loadBuiltinPlugins関数がエントリーポイント |

**主要処理フロー**:
1. **1-6行目**: 環境に応じたプラグインリスト読み込み関数の定義
2. **8-11行目**: キャッシュ機構を使用したloadBuiltinPlugins関数

#### Step 3: プラグインリストの構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | production-plugins.js | `src/main/plugins/builtin-plugins/production-plugins.js` | 本番環境用プラグインリスト |
| 3-2 | development-plugins.js | `src/main/plugins/builtin-plugins/development-plugins.js` | 開発環境用プラグインリスト |

**主要処理フロー**:
- **22-127行目** (production): toLazyLoadPluginsを使用したプラグイン定義
- 各プラグインは`name`、`load`（動的インポート）、`options`、`languages`、`parsers`、`printers`を持つ

#### Step 4: 遅延読み込み機構を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | utilities.js | `src/main/plugins/builtin-plugins/utilities.js` | toLazyLoadPlugin関数の実装 |

**主要処理フロー**:
- **15-58行目**: toLazyLoadPlugin関数でプラグインを遅延読み込み対応に変換
- **23-30行目**: options/languagesは即時設定
- **32-55行目**: parsers/printersは遅延読み込み関数として設定

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

```
loadBuiltinPlugins (load-builtin-plugins.js:9)
    │
    ├─ [キャッシュヒット] → キャッシュから返却
    │
    └─ [キャッシュミス] → loadBuiltinPluginsWithoutCache (load-builtin-plugins.js:1)
           │
           ├─ [本番環境] → production-plugins.js
           │      │
           │      └─ toLazyLoadPlugins (utilities.js:63)
           │             │
           │             └─ toLazyLoadPlugin (utilities.js:15) × N回
           │
           └─ [開発環境] → development-plugins.js
                  │
                  └─ toLazyLoadPlugins (utilities.js:63)
                         │
                         └─ toLazyLoadPlugin (utilities.js:15) × N回
```

### データフロー図

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

環境変数                loadBuiltinPlugins                 プラグイン配列
NODE_ENV ─────────────▶ キャッシュ確認 ─────────────▶    (遅延読み込み対応)
                              │
                              ▼
                    プラグインリスト選択
                    (production/development)
                              │
                              ▼
                    toLazyLoadPlugins
                              │
                    ┌─────────┴─────────┐
                    │                   │
              options/languages    parsers/printers
                    │                   │
                    ▼                   ▼
               即時設定          遅延読み込み関数化
                    │                   │
                    └─────────┬─────────┘
                              │
                              ▼
                        プラグイン配列
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| load-builtin-plugins.js | `src/main/plugins/load-builtin-plugins.js` | ソース | ビルトインプラグインの読み込みエントリーポイント |
| production-plugins.js | `src/main/plugins/builtin-plugins/production-plugins.js` | ソース（自動生成） | 本番環境用プラグインリスト |
| development-plugins.js | `src/main/plugins/builtin-plugins/development-plugins.js` | ソース（自動生成） | 開発環境用プラグインリスト |
| utilities.js | `src/main/plugins/builtin-plugins/utilities.js` | ソース | 遅延読み込みユーティリティ |
| options.js | `src/language-js/options.js` | ソース | JavaScriptオプション定義 |
| options.js | `src/language-css/options.js` | ソース | CSSオプション定義 |
| options.js | `src/language-html/options.js` | ソース | HTMLオプション定義 |
| options.js | `src/language-markdown/options.js` | ソース | Markdownオプション定義 |
| options.js | `src/language-yaml/options.js` | ソース | YAMLオプション定義 |
| generate-builtin-plugins.js | `scripts/generate-builtin-plugins.js` | スクリプト | プラグインリスト自動生成 |
