# 機能設計書 72-@babel/plugin-syntax-flow

## 概要

本ドキュメントは、@babel/plugin-syntax-flowの機能設計について記載する。このパッケージは、BabelパーサーでFlow構文の解析を有効化するための構文プラグインである。

### 本機能の処理概要

**業務上の目的・背景**：FlowはFacebookが開発したJavaScript用の静的型チェッカーであり、多くのReactプロジェクトで採用されている。BabelでFlowを使用したコードを処理するためには、まずFlow固有の構文をパーサーが認識できる必要がある。本プラグインは、Babelパーサーに対してFlow構文の解析機能を有効化し、型アノテーション、type/interface宣言、ジェネリクスなどのFlow固有の構文を解析可能にする。

**機能の利用シーン**：Flowで型付けされたJavaScriptソースコードをBabelで処理する際に使用される。単体では構文の解析のみを行い、型アノテーションの削除などの変換は行わない。変換が必要な場合は、@babel/plugin-transform-flow-strip-typesや@babel/preset-flowと組み合わせて使用する。@flowプラグマがないファイルも解析対象にしたい場合は、allオプションを有効にする。

**主要な処理内容**：
1. プラグインオプション（all）の受け取りとバリデーション
2. Babelバージョンの互換性チェック（^7.0.0-0 || ^8.0.0）
3. enumsオプションの非推奨化対応（削除済み、常時有効）
4. parserOptsへのflowプラグイン設定の追加

**関連システム・外部連携**：@babel/parserと連携し、パーサーオプションを操作する。@babel/helper-plugin-utilsのdeclare関数を使用してプラグインを定義する。

**権限による制御**：権限による実行制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI/ビルドツール経由での利用 |

## 機能種別

構文解析設定 / パーサー設定変更

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| all | boolean | No | @flowプラグマがなくてもすべてのファイルをFlow構文として解析 | boolean型またはundefinedであること |

### 入力データソース

Babel設定ファイル（babel.config.js、.babelrcなど）からプラグインオプションとして取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | string | プラグイン名 "syntax-flow" |
| manipulateOptions | function | パーサーオプションを変更する関数 |

### 出力先

@babel/coreのプラグインシステムに対してPluginObjectを返却

## 処理フロー

### 処理シーケンス

```
1. プラグイン初期化
   └─ declare関数でプラグインファクトリを定義
2. Babelバージョン検証
   └─ api.assertVersionで^7.0.0-0 || ^8.0.0を検証
3. オプション取得とバリデーション
   ├─ allオプションの型チェック（boolean | undefined）
   └─ enumsオプションが設定されていればエラー（削除済み）
4. manipulateOptions実行
   └─ parserOpts.pluginsに["flow", {all}]を追加
```

### フローチャート

```mermaid
flowchart TD
    A[プラグイン読み込み] --> B[declare関数実行]
    B --> C{Babelバージョン検証}
    C -->|失敗| D[バージョンエラー]
    C -->|成功| E{allオプション検証}
    E -->|不正な型| F[型エラーをスロー]
    E -->|正常| G{enumsオプション検証}
    G -->|設定あり| H[非推奨エラーをスロー]
    G -->|設定なし| I[PluginObject返却]
    I --> J[manipulateOptions呼び出し]
    J --> K[parserOpts.plugins配列に追加]
    K --> L[Flow構文解析有効化]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-72-01 | バージョン互換性 | Babel 7.0.0-beta以降またはBabel 8系が必要 | 常時 |
| BR-72-02 | 構文解析のみ | 型アノテーションの削除等の変換は行わない | 常時 |
| BR-72-03 | all型制約 | allオプションはboolean型またはundefinedのみ許容 | allオプション指定時 |
| BR-72-04 | enums非推奨 | enumsオプションは削除済み、常時有効 | enumsオプション指定時 |

### 計算ロジック

特になし

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| BABEL_VERSION_UNSUPPORTED | バージョンエラー | サポートされないBabelバージョン | @babel/coreを更新する |
| - | 型エラー | allがboolean/undefined以外 | allオプションをboolean型に修正 |
| - | 設定エラー | enumsオプションが指定された | enumsオプションを設定から削除 |

### リトライ仕様

リトライ対象外（設定エラーのため）

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

トランザクション処理なし

## パフォーマンス要件

パーサーオプションの設定のみのため、オーバーヘッドは極めて小さい

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

特になし（ソースコード解析のみ）

## 備考

- @babel/preset-flowを使用する場合、このプラグインは自動的に含まれる
- Babel 8でenumsオプションは削除され、Flow enumsは常時サポートされる

---

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

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

### 推奨読解順序

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

まず、プラグインで使用されるオプションの型定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-syntax-flow/src/index.ts` | Optionsインターフェースの定義（3-5行目） |

**読解のコツ**: TypeScriptのインターフェース定義により、allオプションがオプショナルなboolean型であることがわかる。

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

プラグインのエントリーポイントとバリデーションロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-syntax-flow/src/index.ts` | declare関数によるプラグイン定義（7-32行目） |

**主要処理フロー**:
1. **7行目**: declare関数でプラグインファクトリを定義開始
2. **8行目**: api.assertVersionでBabelバージョンの互換性チェック
3. **13行目**: optionsからallとenumsを取得（@ts-expect-errorでBabel 7との互換性対応）
4. **15-17行目**: allオプションの型バリデーション（boolean | undefined）
5. **19-23行目**: enumsオプションが設定されていればエラーをスロー（非推奨対応）
6. **25-31行目**: PluginObjectを返却、manipulateOptionsでflow設定を追加

#### Step 3: 依存ヘルパーを理解する

@babel/helper-plugin-utilsのdeclare関数の役割を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-helper-plugin-utils/src/index.ts` | declare関数の実装（26-52行目） |

**主要処理フロー**:
- **26-52行目**: declare関数はプラグインビルダーをラップし、APIポリフィルを提供する

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

```
@babel/plugin-syntax-flow/src/index.ts
    │
    ├─ @babel/helper-plugin-utils
    │      └─ declare() - プラグイン定義ラッパー
    │
    └─ @babel/core (実行時)
           ├─ api.assertVersion() - バージョン検証
           └─ manipulateOptions() - パーサー設定変更
                  └─ parserOpts.plugins.push()
```

### データフロー図

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

プラグインオプション ───▶ declare()ラッパー ───▶ PluginObject
  - all: boolean?            │
                              │
                              ▼
                      バリデーション
                        │
                        ▼
                   manipulateOptions() ───▶ parserOpts.plugins
                                              └─ ["flow", {all}]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-syntax-flow/src/index.ts` | ソース | プラグインのメイン実装 |
| index.ts | `packages/babel-helper-plugin-utils/src/index.ts` | ソース | declare関数の提供 |
| package.json | `packages/babel-plugin-syntax-flow/package.json` | 設定 | パッケージメタデータと依存関係 |
