# バッチ設計書 48-gulp generate-type-helpers

## 概要

本ドキュメントは、Babelプロジェクトにおける型ヘルパー生成バッチ `gulp generate-type-helpers` の設計について記載する。このバッチは@babel/typesと@babel/traverseの動的関数（asserts、builders、validators等）を自動生成する。

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

**業務上の目的・背景**：@babel/typesパッケージには、ASTノードの検証、アサーション、ビルダー関数など、多数の動的に生成される関数が含まれている。これらの関数を手動で管理するのは非効率で誤りを招きやすいため、ASTノード定義から自動生成する仕組みが必要である。本バッチにより、ノード定義の変更が自動的に関連関数に反映され、型安全性と一貫性が保証される。

**バッチの実行タイミング**：`gulp build` の一部として実行される。また、`gulp build-dev` 内でも実行され、その後に@babel/typesの再ビルドが行われる。`gulp watch` でも型定義ファイル変更時に自動実行される。

**主要な処理内容**：
1. @babel/typesのヘルパー生成
   - asserts: ノード型アサーション関数
   - builders (lowercase.ts, uppercase.ts, index.ts): ノードビルダー関数
   - constants: 定数定義
   - validators: ノードバリデーター関数
   - ast-types: AST型定義
2. @babel/traverseのヘルパー生成
   - path/asserts: パスアサーション型定義
   - path/validators: パスバリデーター型定義
   - visitor-types: ビジター型定義

**前後の処理との関連**：`gulp build` 内では、最初のビルドフェーズ後に実行され、生成されたヘルパーを含む@babel/typesが再度ビルドされる。

**影響範囲**：packages/babel-types/src/*/generated/およびpackages/babel-traverse/src/*/generated/ディレクトリに生成ファイルが出力される。

## バッチ種別

コード生成処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | gulp build時、型定義変更時 |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | gulp generate-type-helpers / gulp build / gulp watch |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js 20以上が必要 |
| 依存関係インストール済み | `yarn install` によりnode_modulesが構築済み |
| 初回ビルド完了 | @babel/types/lib/definitions/が存在すること |

### 実行可否判定

packages/babel-types/lib/definitions/内の定義ファイルと、scripts/generators/内のジェネレータスクリプトが存在すればビルド可能。

## 入力仕様

### 入力パラメータ

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

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| packages/babel-types/lib/definitions/**/*.js | JavaScript | ASTノード定義 |
| packages/babel-types/scripts/generators/*.ts | TypeScript | ヘルパー生成スクリプト |
| packages/babel-traverse/scripts/generators/*.ts | TypeScript | traverse用ヘルパー生成スクリプト |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/babel-types/src/asserts/generated/index.ts | TypeScript | アサーション関数 |
| packages/babel-types/src/builders/generated/lowercase.ts | TypeScript | 小文字ビルダー関数 |
| packages/babel-types/src/builders/generated/uppercase.ts | TypeScript | 大文字ビルダー関数 |
| packages/babel-types/src/builders/generated/index.ts | TypeScript | ビルダーエクスポート |
| packages/babel-types/src/constants/generated/index.ts | TypeScript | 定数定義 |
| packages/babel-types/src/validators/generated/index.ts | TypeScript | バリデーター関数 |
| packages/babel-types/src/ast-types/generated/index.ts | TypeScript | AST型定義 |
| packages/babel-traverse/src/path/generated/asserts.d.ts | TypeScript | パスアサーション型 |
| packages/babel-traverse/src/path/generated/validators.d.ts | TypeScript | パスバリデーター型 |
| packages/babel-traverse/src/generated/visitor-types.d.ts | TypeScript | ビジター型 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 各ヘルパー種別に対応したファイル名 |
| 出力先 | src/*/generated/ |
| 文字コード | UTF-8 |
| ヘッダーコメント | 自動生成警告、再生成コマンド |

## 処理フロー

### 処理シーケンス

```
1. 並列実行される@babel/typesヘルパー生成
   ├─ generateTypeHelpers("asserts")
   │   └─ asserts.ts読込 → index.ts生成
   ├─ generateTypeHelpers("builders", "lowercase.ts")
   │   └─ builders.ts読込 → lowercase.ts生成
   ├─ generateTypeHelpers("builders", "uppercase.ts")
   │   └─ builders.ts読込 → uppercase.ts生成
   ├─ generateTypeHelpers("builders")
   │   └─ builders.ts読込 → index.ts生成
   ├─ generateTypeHelpers("constants")
   │   └─ constants.ts読込 → index.ts生成
   ├─ generateTypeHelpers("validators")
   │   └─ validators.ts読込 → index.ts生成
   └─ generateTypeHelpers("ast-types")
       └─ ast-types.ts読込 → index.ts生成

2. 並列実行される@babel/traverseヘルパー生成
   ├─ generateTraverseHelpers("asserts", "path")
   │   └─ asserts.d.ts生成
   ├─ generateTraverseHelpers("validators", "path")
   │   └─ validators.d.ts生成
   └─ generateTraverseHelpers("visitor-types")
       └─ visitor-types.d.ts生成
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{Promise.all並列実行}
    B --> C[generateTypeHelpers asserts]
    B --> D[generateTypeHelpers builders lowercase]
    B --> E[generateTypeHelpers builders uppercase]
    B --> F[generateTypeHelpers builders index]
    B --> G[generateTypeHelpers constants]
    B --> H[generateTypeHelpers validators]
    B --> I[generateTypeHelpers ast-types]
    B --> J[generateTraverseHelpers asserts]
    B --> K[generateTraverseHelpers validators]
    B --> L[generateTraverseHelpers visitor-types]
    C --> M[Prettier整形]
    D --> M
    E --> M
    F --> M
    G --> M
    H --> M
    I --> M
    J --> M
    K --> M
    L --> M
    M --> N[ファイル書き込み]
    N --> O[バッチ終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | インポートエラー | 定義ファイル未ビルド時 | make buildまたはbuild-no-bundleを実行 |
| - | 生成エラー | テンプレートエラー時 | ジェネレータスクリプトを確認 |
| - | 書き込みエラー | 権限不足時 | ディレクトリ権限を確認 |

### リトライ仕様

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

### 障害時対応

生成エラー時は、定義ファイル（lib/definitions/）のビルド状態を確認する。初回ビルドの場合は先にbuild-no-bundleを実行する必要がある。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 10ファイル |
| 目標処理時間 | 数秒〜30秒 |
| メモリ使用量上限 | 500MB |

## 排他制御

Promise.allで全ヘルパー生成を並列実行する。各ヘルパーは独立したファイルに出力するため、競合は発生しない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | タスク開始時 | Generating @babel/types and @babel/traverse dynamic functions |
| 完了ログ | 各ヘルパー完了時 | Generated @babel/types -> xxx |
| エラーログ | エラー発生時 | エラーメッセージ |

## 監視・アラート

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

## 備考

- 生成されるファイルには「This file is auto-generated! Do not modify it directly.」というコメントが含まれる
- 再生成コマンドは「To re-generate run 'make build'」と記載される
- formatCode関数でPrettierによるフォーマットが適用される
- VISITOR_KEYS、NODE_FIELDS、FLIPPED_ALIAS_KEYS等の定義がlib/から読み込まれる
- DEPRECATED_KEYSとDEPRECATED_ALIASESは非推奨警告付きヘルパーを生成
- 大文字ビルダー（uppercase.ts）は非推奨警告を出力するエイリアス関数
