# バッチ設計書 45-gulp build-rollup

## 概要

本ドキュメントは、Babelプロジェクトにおけるライブラリバンドルバッチ `gulp build-rollup` の設計について記載する。このバッチはRollupを使用して、各パッケージのソースコードをESMフォーマットでバンドルする。

### 本バッチの処理概要

**業務上の目的・背景**：Babelの各パッケージを配布可能な形式にバンドルするためのバッチである。Rollupを使用することで、Tree-shakingに最適化されたESMモジュールを生成し、エンドユーザーのバンドルサイズを削減できる。また、複数のエントリポイントを持つパッケージも効率的にバンドルできる。本番ビルドやnpmパッケージ公開時に必要となる重要な処理である。

**バッチの実行タイミング**：`gulp build` の一部として自動実行される。また、Rollupバンドルのみを更新したい場合に単独で実行することも可能。

**主要な処理内容**：
1. 対象パッケージの特定：package.jsonのexportsフィールドから各パッケージのエントリポイントを抽出
2. Rollupビルド設定の構築：外部依存関係、プラグイン、出力オプションの設定
3. バンドル実行：TypeScript/JavaScriptソースをESMフォーマットでバンドル
4. ソースマップ生成：本番環境（NODE_ENV=production）時にソースマップを生成
5. 出力ファイル生成：lib/ディレクトリにバンドル済みファイルを出力

**前後の処理との関連**：`gulp build` 内で `build-babel` と並列実行される。ヘルパー生成タスク（generate-type-helpers等）の後に再度実行されることで、生成されたヘルパーを含むバンドルが作成される。

**影響範囲**：packages、codemodsディレクトリ配下の対象パッケージのlib/ディレクトリにバンドルファイルが生成される。一部のパッケージ（babel-standalone、babel-cli等）は除外される。

## バッチ種別

ビルド処理（バンドル）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | gulp build実行時、または随時 |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | gulp build経由またはyarn gulp build-rollup |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js 20以上が必要 |
| 依存関係インストール済み | `yarn install` によりnode_modulesが構築済みであること |
| Rollup依存関係 | @rollup/plugin-*、rollup-plugin-*がインストール済み |

### 実行可否判定

各パッケージのpackage.jsonにexportsフィールドが定義されており、ソースファイルが存在すればビルド可能。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| NODE_ENV | 環境変数 | No | development | productionでソースマップ生成 |
| BABEL_9_BREAKING | 環境変数 | No | false | trueでBabel 9向けビルド |
| STRIP_BABEL_VERSION_FLAG | 環境変数 | No | false | バージョンフラグ除去の有効化 |
| CIRCLE_PR_NUMBER | 環境変数 | No | 未設定 | PRサフィックスのバージョン付与 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| packages/*/src/**/*.ts | TypeScript | 各パッケージのソースコード |
| packages/*/package.json | JSON | エントリポイント定義（exports） |
| codemods/*/src/**/*.ts | TypeScript | codemodのソースコード |
| babel.config.ts | TypeScript | Babelトランスパイル設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/*/lib/*.js | JavaScript (ESM) | バンドルされたJSファイル |
| packages/*/lib/*.js.map | Source Map | ソースマップ（production時） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 元ファイル名の拡張子を.ts→.js等に変換 |
| 出力先 | packages/*/lib/ |
| 文字コード | UTF-8 |
| モジュール形式 | ESM (ES Modules) |

## 処理フロー

### 処理シーケンス

```
1. パッケージ列挙
   └─ libBundlesIteratorでバンドル対象パッケージを列挙

2. 各パッケージの処理（並列）
   ├─ package.json読み込み
   │   └─ exports/importsからエントリポイント抽出
   ├─ 外部依存関係設定
   │   └─ dependencies/peerDependenciesを外部化
   ├─ Rollup設定構築
   │   ├─ rollupBabelSource（ソース変換）
   │   ├─ rollupReplace（定数置換）
   │   ├─ rollupCommonJs（CJS変換）
   │   ├─ rollupBabel（Babelトランスパイル）
   │   ├─ rollupNodeResolve（モジュール解決）
   │   └─ rollupJson（JSON読み込み）
   ├─ バンドル実行
   └─ 出力ファイル書き込み
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[libBundlesIteratorで<br>対象パッケージ列挙]
    B --> C[各パッケージを並列処理]
    C --> D[package.json読み込み]
    D --> E[エントリポイント抽出]
    E --> F[外部依存関係設定]
    F --> G[Rollupプラグイン設定]
    G --> H[Rollupバンドル実行]
    H --> I[lib/に出力]
    I --> J[バッチ終了]
```

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

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

本バッチはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| CIRCULAR_DEPENDENCY | 警告（無視） | 循環依存検出時 | コードの依存関係を確認（通常は問題なし） |
| MISSING_EXPORT | エラー | エクスポートが見つからない | コードのexport文を確認 |
| - | バンドルエラー | 依存関係解決失敗時 | yarn installの再実行 |
| - | TypeScriptエラー | 型エラーがある場合 | ソースコードの型エラーを修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

バンドルエラー時はエラーメッセージを確認し、該当するパッケージのソースコードまたはpackage.jsonの設定を修正する。MISSING_EXPORTエラーの場合は、エクスポート元モジュールの存在と正確性を確認する。

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

本バッチはデータベーストランザクションを使用しない。

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約100パッケージ |
| 目標処理時間 | 2〜5分 |
| メモリ使用量上限 | 2GB〜4GB |

## 排他制御

Promise.allで全パッケージを並列処理するため、CPUとI/Oリソースを効率的に使用する。同一パッケージへの同時書き込みは発生しない設計。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各バンドル開始時 | Compiling 'xxx' with rollup ... |
| 警告ログ | 警告発生時 | Rollup警告メッセージ |
| エラーログ | エラー発生時 | エラーメッセージ、スタックトレース |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド時間 | 10分超過 | CI/CDシステム通知 |
| ビルド失敗 | 1回 | CI/CDシステム通知 |

## 備考

- 除外パッケージ一覧:
  - babel-helper-fixtures（commonjsプラグインとの競合）
  - babel-standalone（専用タスクで処理）
  - babel-cli（hashbangによるハング問題）
  - babel-register（#import条件の維持）
  - babel-node（内部lib/_babel-node.jsへのアクセス）
  - babel-helpers（test/helpers/define-helperの内部アクセス）
  - babel-helper-builder-react-jsx（Rollupバグ）
  - babel-helper-transform-fixture-test-runner（exit-loader.cjs）
  - babel-runtime, babel-runtime-corejs3（多数のエントリポイント）
- BABEL_VERSIONとVERSIONはrollupReplaceで置換される
- getBabelOutputPluginはbabel-parserとbabel-generatorに対して追加の最適化を適用
