# 機能設計書 17-@babel/preset-typescript

## 概要

本ドキュメントは、Babelの@babel/preset-typescriptパッケージの機能設計を記述する。@babel/preset-typescriptは、TypeScriptコードをJavaScriptに変換するためのプリセットである。

### 本機能の処理概要

@babel/preset-typescriptは、TypeScriptの型アノテーションを削除し、TypeScript固有の構文（enum、名前空間など）をJavaScriptに変換する。型チェックは行わず、構文の変換のみを担当する。

**業務上の目的・背景**：TypeScriptは型安全性を提供する人気の高い言語だが、実行時にはJavaScriptに変換する必要がある。従来はtsc（TypeScriptコンパイラ）を使用していたが、Babelを使用することでより柔軟な変換パイプラインを構築でき、他のBabelプラグインとの統合も容易になる。型チェックはtscやtsserverに任せ、変換のみをBabelが担当することで、高速なビルドと柔軟な設定が可能になる。

**機能の利用シーン**：TypeScriptプロジェクトのビルド、Reactコンポーネント（TSX）の変換、Node.jsバックエンドのTypeScriptコンパイル、ライブラリの配布用ビルドなどで利用される。

**主要な処理内容**：
1. 型アノテーションの削除（@babel/plugin-transform-typescript）
2. ファイル拡張子による自動設定（.ts, .tsx, .mts, .cts）
3. enum構文の変換
4. 名前空間のサポート（allowNamespaces）
5. インポート拡張子の書き換え（rewriteImportExtensions）
6. 曖昧なJSXライクな式の禁止（disallowAmbiguousJSXLike）

**関連システム・外部連携**：@babel/plugin-transform-typescript、@babel/plugin-transform-modules-commonjsと連携。

**権限による制御**：本機能に権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | なし | - | CLIおよびAPIとして利用 |

## 機能種別

プリセット / TypeScript変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ignoreExtensions | boolean | No | 拡張子による自動設定を無効化 | デフォルト: false |
| allowNamespaces | boolean | No | TypeScript名前空間を許可 | デフォルト: true |
| disallowAmbiguousJSXLike | boolean | No | 曖昧なJSXライク式を禁止 | デフォルト: false |
| jsxPragma | string | No | JSX pragma | デフォルト: "React" |
| jsxPragmaFrag | string | No | JSX Fragment pragma | デフォルト: "React.Fragment" |
| onlyRemoveTypeImports | boolean | No | 型のみのインポートだけ削除 | デフォルト: false |
| optimizeConstEnums | boolean | No | const enumを最適化 | デフォルト: false |
| rewriteImportExtensions | boolean | No | インポート拡張子を書き換え | デフォルト: false |

### 入力データソース

- Babel設定ファイル（babel.config.js, .babelrc等）
- API呼び出しのオプション

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| plugins | array | 適用するプラグインの配列 |
| overrides | array | ファイル拡張子別の設定 |

### 出力先

Babelコア(@babel/core)に対してプラグイン配列とoverridesを返却する。

## 処理フロー

### 処理シーケンス

```
1. オプションの正規化
   └─ normalizeOptions: デフォルト値設定

2. rewriteImportExtensionsプラグインの追加
   └─ 有効時: pluginRewriteTSImportsを追加

3. ファイル拡張子による設定分岐
   └─ ignoreExtensions: true → 単一設定
   └─ ignoreExtensions: false → overridesで拡張子別設定
       ├─ .ts: disallowAmbiguousJSXLike: false
       ├─ .mts: sourceType: module, disallowAmbiguousJSXLike: true
       ├─ .cts: sourceType: unambiguous, CommonJS変換追加
       └─ .tsx: disallowAmbiguousJSXLike: false (JSXのため不要)

4. プラグイン配列の返却
```

### フローチャート

```mermaid
flowchart TD
    A[preset-typescript呼び出し] --> B[normalizeOptions]
    B --> C{rewriteImportExtensions?}
    C -->|Yes| D[pluginRewriteTSImports追加]
    C -->|No| E{ignoreExtensions?}
    D --> E
    E -->|Yes| F[単一プラグイン設定]
    E -->|No| G[overrides設定]
    G --> H[.ts用設定]
    G --> I[.mts用設定]
    G --> J[.cts用設定]
    G --> K[.tsx用設定]
    H --> L[返却]
    I --> L
    J --> L
    K --> L
    F --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 型チェック非実施 | Babelは型チェックを行わない | 常時 |
| BR-02 | .mts = ESM | .mtsファイルはESモジュールとして処理 | .mtsファイル |
| BR-03 | .cts = CommonJS | .ctsファイルはCommonJSとして処理 | .ctsファイル |
| BR-04 | TSX優先 | .tsxではJSX構文を優先、型アサーションは`as`を使用 | .tsxファイル |
| BR-05 | 曖昧式禁止 | .mts/.ctsでは`<T>(x)`のような曖昧な式を禁止 | .mts/.ctsファイル |

### 計算ロジック

TypeScript変換例:
```typescript
// 入力
interface User {
  name: string;
  age: number;
}
const user: User = { name: "John", age: 30 };

// 出力（型アノテーション削除）
const user = { name: "John", age: 30 };
```

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | SyntaxError | 不正なTypeScript構文 | コードを修正 |
| - | Error | .mtsで曖昧なJSXライク式 | `as`構文を使用 |

### リトライ仕様

本機能にリトライ処理は存在しない。

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

本機能はトランザクション処理を行わない。

## パフォーマンス要件

- 型チェックを行わないため、tscより高速
- 単一パスで変換完了

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

- 入力コードの検証は行わない
- 変換のみを実行

## 備考

- 型チェックは別途tscまたはtsserverで実行すること
- enumの変換はランタイムオーバーヘッドを伴う
- const enumはoptimizeConstEnumsでインライン化可能

---

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

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

### 推奨読解順序

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

まず、プリセットのメイン処理を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-preset-typescript/src/index.ts` | プリセットのメイン実装 |

**読解のコツ**:
- **1-7行目**: インポート文。transformTypeScriptとtransformModulesCommonJSをインポート
- **9-22行目**: declarePreset関数の開始とオプション取得
- **23-30行目**: pluginOptions関数の定義
- **32-38行目**: getPlugins関数の定義
- **40行目**: disableExtensionDetectの設定
- **42-73行目**: overrides設定による拡張子別処理

#### Step 2: 拡張子別設定を理解する

ファイル拡張子によって異なる設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-preset-typescript/src/index.ts` | 48-72行目のoverrides |

**主要処理フロー**:
- **48-52行目**: .ts用設定（filename == null または .tsで終わる）
- **53-57行目**: .mts用設定（sourceType: module, disallowAmbiguousJSXLike: true）
- **58-66行目**: .cts用設定（CommonJS変換プラグイン追加）
- **67-71行目**: .tsx用設定（JSX優先のためdisallowAmbiguousJSXLike: false）

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

オプションの検証と正規化処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | normalize-options.ts | `packages/babel-preset-typescript/src/normalize-options.ts` | オプション正規化 |

#### Step 4: インポート拡張子書き換えを理解する

.ts/.tsx → .js変換を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | plugin-rewrite-ts-imports.ts | `packages/babel-preset-typescript/src/plugin-rewrite-ts-imports.ts` | インポートパス書き換え |

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

```
@babel/preset-typescript
    │
    ├─ declarePreset (@babel/helper-plugin-utils)
    │
    ├─ normalizeOptions
    │      └─ オプションの検証と正規化
    │
    ├─ plugins[] (rewriteImportExtensions有効時)
    │      └─ pluginRewriteTSImports
    │
    └─ overrides[] (ignoreExtensions無効時)
           │
           ├─ test: .ts
           │      └─ @babel/plugin-transform-typescript
           │
           ├─ test: .mts
           │      ├─ sourceType: "module"
           │      └─ @babel/plugin-transform-typescript
           │
           ├─ test: .cts
           │      ├─ sourceType: "unambiguous"
           │      ├─ @babel/plugin-transform-modules-commonjs
           │      └─ @babel/plugin-transform-typescript
           │
           └─ test: .tsx
                  └─ @babel/plugin-transform-typescript
```

### データフロー図

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

TypeScriptコード ─────> normalizeOptions ────────────────┐
                                                         │
ファイル拡張子 ────────> test関数でマッチ ─────────────────┤
                                                         │
                                                         └──> transform-typescript
                                                                      │
                                                         型アノテーション削除
                                                         enum変換
                                                         名前空間変換
                                                                      │
                                                         JavaScriptコード
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-preset-typescript/src/index.ts` | ソース | プリセットメイン実装 |
| normalize-options.ts | `packages/babel-preset-typescript/src/normalize-options.ts` | ソース | オプション正規化 |
| plugin-rewrite-ts-imports.ts | `packages/babel-preset-typescript/src/plugin-rewrite-ts-imports.ts` | ソース | インポート拡張子書き換え |
| package.json | `packages/babel-preset-typescript/package.json` | 設定 | パッケージ設定 |
| test/index.js | `packages/babel-preset-typescript/test/index.js` | テスト | ユニットテスト |
