# 機能設計書 71-@babel/plugin-syntax-typescript

## 概要

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

### 本機能の処理概要

**業務上の目的・背景**：TypeScriptはJavaScriptに静的型付けを追加した言語であり、現代のフロントエンド・バックエンド開発において広く採用されている。Babelでこれらのコードを処理するためには、まずTypeScript固有の構文をパーサーが認識できる必要がある。本プラグインは、Babelパーサーに対してTypeScript構文の解析機能を有効化し、型アノテーション、インターフェース、enum、ジェネリクスなどのTypeScript固有の構文を解析可能にする。

**機能の利用シーン**：TypeScriptで記述されたソースコードをBabelで処理する際に使用される。単体では構文の解析のみを行い、型アノテーションの削除などの変換は行わない。変換が必要な場合は、@babel/plugin-transform-typescriptや@babel/preset-typescriptと組み合わせて使用する。特に、カスタム変換プラグインを開発する際や、TypeScript構文を解析のみ行いたい場合に有用である。

**主要な処理内容**：
1. プラグインオプション（disallowAmbiguousJSXLike、dts、isTSX）の受け取り
2. Babelバージョンの互換性チェック（^7.0.0-0 || ^8.0.0）
3. parserOptsへのtypescriptプラグイン設定の追加
4. .d.tsファイル解析用のdtsオプション対応

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| disallowAmbiguousJSXLike | boolean | No | JSXと曖昧な構文を禁止する | boolean型であること |
| dts | boolean | No | .d.tsファイルとして解析する | boolean型であること |
| isTSX | boolean | No | TSX構文を有効にする | boolean型であること |

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. プラグイン初期化
   └─ declare関数でプラグインファクトリを定義
2. Babelバージョン検証
   └─ api.assertVersionで^7.0.0-0 || ^8.0.0を検証
3. オプション取得
   └─ opts.disallowAmbiguousJSXLike、opts.dtsを取得
4. manipulateOptions実行
   └─ parserOpts.pluginsに["typescript", {disallowAmbiguousJSXLike, dts}]を追加
```

### フローチャート

```mermaid
flowchart TD
    A[プラグイン読み込み] --> B[declare関数実行]
    B --> C{Babelバージョン検証}
    C -->|失敗| D[エラーをスロー]
    C -->|成功| E[オプション取得]
    E --> F[PluginObject返却]
    F --> G[manipulateOptions呼び出し]
    G --> H[parserOpts.plugins配列に追加]
    H --> I[TypeScript構文解析有効化]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-71-01 | バージョン互換性 | Babel 7.0.0-beta以降またはBabel 8系が必要 | 常時 |
| BR-71-02 | 構文解析のみ | 型アノテーションの削除等の変換は行わない | 常時 |

### 計算ロジック

特になし

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| BABEL_VERSION_UNSUPPORTED | バージョンエラー | サポートされないBabelバージョン | @babel/coreを更新する |

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- @babel/preset-typescriptを使用する場合、このプラグインは自動的に含まれる
- .tsxファイルを解析する場合はisTSXオプションを使用する

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: TypeScriptのインターフェース定義により、プラグインが受け取れるオプションが明確に定義されている。disallowAmbiguousJSXLike、dts、isTSXの3つのオプションがすべてオプショナルである点に注目。

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

プラグインのエントリーポイントとなるdeclare関数の呼び出しを確認する。

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

**主要処理フロー**:
1. **9行目**: declare関数でプラグインファクトリを定義開始
2. **10行目**: api.assertVersionでBabelバージョンの互換性チェック
3. **12行目**: optsからdisallowAmbiguousJSXLikeとdtsを分割代入で取得
4. **14-22行目**: PluginObjectを返却、nameとmanipulateOptionsを定義
5. **17-21行目**: manipulateOptions内でparserOpts.pluginsにtypescript設定を追加

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

### データフロー図

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

プラグインオプション ───▶ declare()ラッパー ───▶ PluginObject
  - disallowAmbiguousJSXLike      │
  - dts                            │
  - isTSX                          ▼
                           manipulateOptions() ───▶ parserOpts.plugins
                                                      └─ ["typescript", {...}]
```

### 関連ファイル一覧

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