# バッチ設計書 50-gulp generate-standalone

## 概要

本ドキュメントは、Babelプロジェクトにおける@babel/standaloneプラグインリスト生成バッチ `gulp generate-standalone` の設計について記載する。このバッチはpluginConfig.jsonからプラグインリストを読み込み、plugins.tsファイルを自動生成する。

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

**業務上の目的・背景**：@babel/standaloneパッケージでは、多数のBabelプラグインをブラウザ上で使用可能にする必要がある。プラグインの追加・削除を手動で管理するのは煩雑でエラーを招きやすいため、設定ファイルから自動生成する仕組みが必要である。本バッチにより、pluginConfig.jsonを更新するだけで新しいプラグインを@babel/standaloneに追加できる。

**バッチの実行タイミング**：`gulp build` の最後に実行される。また、`gulp build-babel-standalone` の前処理として実行される。`gulp watch` でpluginConfig.jsonの変更時に自動実行される。

**主要な処理内容**：
1. pluginConfig.jsonの読み込み
2. noopPlugins: 何も処理しないプラグイン（シンタックスプラグイン等）のエクスポート生成
3. externalPlugins: 実際に変換処理を行うプラグインのimport/export生成
4. all: 全プラグインをプラグイン名（短縮形）でアクセス可能なオブジェクト生成
5. plugins.tsファイルの出力

**前後の処理との関連**：`gulp build` 内では最後に実行され、生成されたplugins.tsは `rollup-babel-standalone` タスクでバンドルに含まれる。

**影響範囲**：packages/babel-standalone/src/generated/plugins.tsが生成・更新される。このファイルは@babel/standaloneの機能に直接影響する。

## バッチ種別

コード生成処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | gulp build時、pluginConfig.json変更時 |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | gulp generate-standalone / gulp build / gulp watch |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js 20以上が必要 |
| 依存関係インストール済み | `yarn install` によりnode_modulesが構築済み |
| pluginConfig.json存在 | 設定ファイルが存在すること |

### 実行可否判定

packages/babel-standalone/scripts/pluginConfig.jsonが存在すればビルド可能。

## 入力仕様

### 入力パラメータ

本バッチは環境変数による設定は行わない。

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| packages/babel-standalone/scripts/pluginConfig.json | JSON | プラグイン設定 |

pluginConfig.jsonの構造：
```json
{
  "noopPlugins": ["syntax-async-generators", ...],
  "unexposedNoopPlugins": ["syntax-logical-assignment-operators", ...],
  "externalPlugins": ["external-helpers", "transform-async-to-generator", ...]
}
```

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/babel-standalone/src/generated/plugins.ts | TypeScript | 生成されたプラグインリスト |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | plugins.ts |
| 出力先 | packages/babel-standalone/src/generated/ |
| 文字コード | UTF-8 |
| ヘッダーコメント | 自動生成警告、再生成コマンド |

生成されるファイルの構造：
```typescript
/*
 * This file is auto-generated! Do not modify it directly.
 * To re-generate run 'yarn gulp generate-standalone'
 */
import makeNoopPlugin from "../make-noop-plugin.ts";
import transformAsyncToGenerator from "@babel/plugin-transform-async-to-generator";
// ... 他のimport

export const syntaxAsyncGenerators = makeNoopPlugin(), ...;
export { transformAsyncToGenerator, ... };
export const all: Record<string, any> = {
  "async-to-generator": transformAsyncToGenerator,
  // ...
};
```

## 処理フロー

### 処理シーケンス

```
1. pluginConfig.json読み込み
   └─ gulp.srcでファイルを読み込み

2. Transform処理
   ├─ noopPlugins処理
   │   └─ makeNoopPlugin()でexport宣言を生成
   ├─ externalPlugins処理
   │   ├─ @babel/plugin-xxxからのimport文生成
   │   └─ export文生成
   └─ all オブジェクト生成
       └─ 短縮プラグイン名: 変数名の対応を生成

3. 出力ファイル生成
   ├─ ヘッダーコメント
   ├─ import文
   ├─ export const宣言
   ├─ export { }文
   ├─ all オブジェクト
   └─ formatCodeでPrettier整形

4. ファイル書き込み
   └─ src/generated/plugins.tsに出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[pluginConfig.json読込]
    B --> C[JSON解析]
    C --> D[noopPluginsループ]
    D --> E[kebabToCamel変換]
    E --> F[makeNoopPlugin export生成]
    F --> G[externalPluginsループ]
    G --> H[import文生成]
    H --> I[export追加]
    I --> J[all オブジェクトエントリ追加]
    J --> K[ファイルコンテンツ構築]
    K --> L[formatCode Prettier整形]
    L --> M[src/generated/plugins.ts出力]
    M --> N[バッチ終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | JSON解析エラー | pluginConfig.jsonが不正な場合 | JSONの構文を確認 |
| - | 書き込みエラー | 権限不足時 | ディレクトリ権限を確認 |

### リトライ仕様

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

### 障害時対応

生成エラー時は、pluginConfig.jsonの構文とプラグイン名の形式を確認する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約100プラグイン |
| 目標処理時間 | 数秒 |
| メモリ使用量上限 | 100MB |

## 排他制御

単一の出力ファイルを生成するため、同時実行時は競合の可能性がある。通常はgulpタスク内で順次実行されるため問題にならない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | タスク開始時 | Generating @babel/standalone files |
| 完了ログ | 生成完了時 | （gulpの標準出力） |
| エラーログ | エラー発生時 | エラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 生成失敗 | 1回 | CI/CDシステム通知 |

## 備考

- kebabToCamel関数でプラグイン名をケバブケースからキャメルケースに変換
  - 例: "async-generators" → "asyncGenerators"
- noopPluginsはmakeNoopPlugin()を呼び出し、何も処理しないプラグインを生成
- unexposedNoopPluginsはpluginConfig.jsonに定義されているが、現在の実装では使用されていない模様
- externalPluginsは@babel/plugin-xxxパッケージからインポートされる
- allオブジェクトはプラグインの短縮名（"transform-"や"proposal-"を含む）でアクセス可能
- gulp.srcとTransformStreamを使用したストリームベースの処理
- 出力ファイルには自動生成警告が含まれる
