# バッチ設計書 42-gulp build

## 概要

本ドキュメントは、Babelプロジェクトにおけるフルビルドバッチ `gulp build` の設計について記載する。このバッチはBabelのすべてのパッケージをコンパイルし、Rollupによるバンドル、型定義ヘルパー、ランタイムヘルパー、standaloneファイルの生成までを含む包括的なビルドを実行する。

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

**業務上の目的・背景**：Babelプロジェクト全体の本番環境向けビルドを実行するための中核的なバッチである。開発中のコード変更を反映し、配布可能な形式のパッケージを生成する。CI/CDパイプラインでの使用、リリース準備、および本番環境デプロイ前の検証において重要な役割を果たす。モノレポ構造の複数パッケージを一貫した方法でビルドし、依存関係の整合性を保証する。

**バッチの実行タイミング**：開発者がローカル環境で手動実行、またはCI/CDパイプライン（CircleCI/GitHub Actions）での自動実行。リリース前の準備段階、大きな機能変更後、または依存関係の更新後に実行される。

**主要な処理内容**：
1. Rollupによるライブラリのバンドル（build-rollup）とBabelによるソースコンパイル（build-babel）の並列実行
2. 型定義ヘルパー（generate-type-helpers）、ランタイムヘルパー（generate-runtime-helpers）、グローバルヘルパーデータ（generate-helper-globals-data）の並列生成
3. ヘルパー生成により変更された@babel/typesと@babel/helpersの再ビルド
4. @babel/standaloneのプラグインリスト生成（generate-standalone）

**前後の処理との関連**：ビルド前に `yarn install` による依存関係のインストールが必要。ビルド後は `make test` でテスト実行、`make lint` でリント検証、`make prepublish` でnpm公開準備が可能となる。

**影響範囲**：packages、codemods、eslintディレクトリ配下の全パッケージのlib/ディレクトリにビルド成果物が生成される。@babel/standaloneのbabel.jsファイル、各パッケージの型定義ファイル（.d.ts）も影響を受ける。

## バッチ種別

ビルド処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動実行またはCI/CD自動実行） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動（make build）またはCI/CDパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js 20以上が必要 |
| 依存関係インストール済み | `yarn install` によりnode_modulesが構築済みであること |
| ディスク容量 | ビルド成果物のための十分なディスク容量（数GB推奨） |
| メモリ | 並列ビルドのため十分なメモリ（8GB以上推奨） |

### 実行可否判定

package.jsonとyarn.lockが存在し、node_modulesが正しく構築されていればビルドは実行可能。TypeScript設定ファイル（tsconfig.json）が必要。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| NODE_ENV | 環境変数 | No | development | production設定時、ソースマップを生成 |
| BABEL_9_BREAKING | 環境変数 | No | false | trueでBabel 9向けビルドを実行 |
| STRIP_BABEL_VERSION_FLAG | 環境変数 | No | false | バージョンフラグを除去するかどうか |
| CIRCLECI | 環境変数 | No | 未設定 | CircleCI環境を示すフラグ（ワーカー設定に影響） |
| IS_PUBLISH | 環境変数 | No | false | 公開ビルド時に圧縮版も生成 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| packages/*/src/**/*.ts | TypeScript | 各パッケージのソースコード |
| codemods/*/src/**/*.ts | TypeScript | codemodのソースコード |
| eslint/*/src/**/*.ts | TypeScript | ESLintプラグインのソースコード |
| babel.config.ts | TypeScript | Babelの設定ファイル |
| Gulpfile.ts | TypeScript | Gulpタスク定義 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/*/lib/ | JavaScript | コンパイル済みのJSファイル |
| packages/*/lib/*.d.ts | TypeScript定義 | 型定義ファイル |
| packages/babel-standalone/babel.js | JavaScript | standaloneビルド |
| packages/babel-types/src/*/generated/ | TypeScript | 生成された型ヘルパー |
| packages/babel-helpers/src/helpers-generated.ts | TypeScript | 生成されたランタイムヘルパー |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 元ファイル名の拡張子を.ts→.js、.cts→.cjs等に変換 |
| 出力先 | src/をlib/に置換したパス |
| 文字コード | UTF-8 |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. 第1フェーズ（並列実行）
   ├─ build-rollup: Rollupでライブラリをバンドル
   └─ build-babel: Babelでソースをコンパイル

2. 第2フェーズ（並列実行）
   ├─ generate-type-helpers: @babel/typesヘルパー生成
   ├─ generate-runtime-helpers: @babel/helpersヘルパー生成
   └─ generate-helper-globals-data: グローバルヘルパーデータ生成

3. 第3フェーズ（並列実行）
   ├─ build-rollup: 生成されたヘルパーを含むパッケージの再バンドル
   └─ build-babel: 生成されたヘルパーを含むソースの再コンパイル

4. 第4フェーズ
   └─ generate-standalone: @babel/standaloneプラグインリスト生成
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[build-rollup & build-babel<br>並列実行]
    B --> C[generate-type-helpers &<br>generate-runtime-helpers &<br>generate-helper-globals-data<br>並列実行]
    C --> D[build-rollup & build-babel<br>再ビルド並列実行]
    D --> E[generate-standalone]
    E --> F[バッチ終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | TypeScriptコンパイルエラー | 型エラーがある場合 | ソースコードの型エラーを修正 |
| - | Rollupバンドルエラー | 依存関係解決失敗時 | yarn installの再実行、依存関係の確認 |
| - | メモリ不足 | 大規模並列ビルド時 | ワーカー数の削減、メモリ増設 |
| - | ファイルシステムエラー | 権限不足またはディスク容量不足 | 権限確認、ディスク容量確保 |

### リトライ仕様

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

### 障害時対応

ビルド失敗時は `make clean` でビルド成果物をクリーンアップし、`yarn install` で依存関係を再インストールしてから再度ビルドを試行する。TypeScriptエラーの場合は `make tscheck` で型チェックを個別に実行して問題を特定する。

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

本バッチはデータベーストランザクションを使用しない。ファイルシステム操作は原子的ではないため、ビルド中の中断時はクリーンアップが必要。

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約150パッケージ |
| 目標処理時間 | 5〜15分（環境依存） |
| メモリ使用量上限 | 4GB〜8GB |

## 排他制御

同一ディレクトリでの同時ビルドは推奨されない。ファイル書き込みの競合が発生する可能性がある。jest-workerを使用した並列処理では、CPUコア数の半分をワーカーに割り当てる（CircleCIではワーカーを使用しない）。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各タスク開始時 | Compiling 'xxx' with rollup ... |
| 進捗ログ | ヘルパー生成時 | Generated @babel/types -> xxx |
| 終了ログ | バッチ終了時 | Gulpタスク完了通知 |
| エラーログ | エラー発生時 | エラーメッセージ、スタックトレース |

## 監視・アラート

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

## 備考

- `gulp build` は `gulp.series` で定義されており、各フェーズは順次実行される
- 第1フェーズと第3フェーズのRollupビルドとBabelビルドは `gulp.parallel` で並列実行される
- CircleCI環境ではワーカースレッドの使用が無効化される（ハングアップ回避のため）
- PR番号が設定されている場合、バージョン番号にサフィックスが付与される
