# バッチ設計書 44-gulp watch

## 概要

本ドキュメントは、Babelプロジェクトにおけるファイル監視・自動ビルドバッチ `gulp watch` の設計について記載する。このバッチはソースファイルの変更を監視し、変更が検出されると自動的に必要なビルドタスクを実行する。

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

**業務上の目的・背景**：開発者がコード変更を行った際に、手動でビルドコマンドを実行する手間を省き、自動的にビルドを行うことで開発効率を向上させるためのバッチである。ファイル保存のたびに即座にビルドが実行されるため、変更の影響をリアルタイムで確認できる。特にテスト駆動開発やインクリメンタルな機能開発において重要な役割を果たす。

**バッチの実行タイミング**：開発者がローカル環境で手動実行。開発セッションの開始時に起動し、開発終了まで継続的に実行される常駐プロセスとして動作する。

**主要な処理内容**：
1. 初回ビルド（WATCH_SKIP_BUILD未設定時のみ）：build-devタスクの実行
2. ソースファイル監視：packages/codemods/eslintディレクトリ配下の.ts/.js/.ctsファイル変更を検出
3. プラグイン設定監視：pluginConfig.jsonの変更を検出
4. 型定義監視：babel-types定義ファイルとスクリプトの変更を検出
5. ヘルパー監視：babel-helpersのhelpers/ディレクトリ変更を検出
6. パーサー監視：babel-parserのソースファイル変更を検出

**前後の処理との関連**：watch開始前に `yarn install` による依存関係のインストールが必要。watchプロセス実行中はターミナルが占有されるため、別のターミナルでテスト実行やその他の操作を行う。

**影響範囲**：監視対象のファイル変更に応じて、対応するビルドタスクが実行される。build-no-bundle-watch、generate-standalone、generate-type-helpers、generate-runtime-helpers、bundle-babel-parser-dtsの各タスクが影響を受ける。

## バッチ種別

ファイル監視・自動ビルド処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 開発セッション中継続的に実行 |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動起動（yarn gulp watch）、その後ファイル変更イベント |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js 20以上が必要 |
| 依存関係インストール済み | `yarn install` によりnode_modulesが構築済みであること |
| ファイルシステム監視対応 | OSがファイルシステム変更イベントをサポートしていること |

### 実行可否判定

package.jsonとnode_modulesが存在すれば実行可能。ファイルシステム監視機能はgulpに内蔵されているため、追加設定は不要。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| WATCH_SKIP_BUILD | 環境変数 | No | false | trueで初回ビルドをスキップし、監視のみ開始 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| ./@(codemods\|packages\|eslint)/*/src/**/*.{js,cjs,ts,cts,mts} | ソースファイル | 監視対象のソースコード |
| packages/babel-standalone/scripts/pluginConfig.json | JSON | standaloneプラグイン設定 |
| packages/babel-types/lib/definitions/**/*.js | JavaScript | 型定義ファイル |
| packages/babel-types/scripts/generators/*.ts | TypeScript | 型生成スクリプト |
| packages/babel-helpers/src/helpers/* | TypeScript/JavaScript | ヘルパーソース |
| packages/babel-parser/src/**/*.ts | TypeScript | パーサーソース |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 監視状態、ビルド開始・完了の通知 |
| packages/*/lib/ | JavaScript | 変更検出時に生成されるビルド成果物 |

### 出力ファイル仕様

ファイル変更に応じて、対応するビルドタスクの出力仕様に従う。

## 処理フロー

### 処理シーケンス

```
1. 初回ビルド判定
   └─ WATCH_SKIP_BUILD未設定時、build-devを実行

2. ファイルウォッチャー設定
   ├─ ソースファイル監視
   │   └─ 変更検出時: build-no-bundle-watch実行
   ├─ pluginConfig.json監視
   │   └─ 変更検出時: generate-standalone実行
   ├─ 型定義ファイル監視
   │   └─ 変更検出時: generate-type-helpers実行
   ├─ helpersディレクトリ監視
   │   └─ 変更検出時: generate-runtime-helpers実行
   └─ babel-parserソース監視
       └─ 変更検出時: bundle-babel-parser-dts実行

3. 監視ループ
   └─ ファイル変更イベントを待機し、対応タスクを実行
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{WATCH_SKIP_BUILD?}
    B -->|No| C[build-dev実行]
    B -->|Yes| D[監視開始]
    C --> D
    D --> E[ファイル変更待機]
    E --> F{変更検出}
    F -->|ソースファイル| G[build-no-bundle-watch]
    F -->|pluginConfig.json| H[generate-standalone]
    F -->|型定義ファイル| I[generate-type-helpers]
    F -->|helpers| J[generate-runtime-helpers]
    F -->|babel-parser| K[bundle-babel-parser-dts]
    G --> E
    H --> E
    I --> E
    J --> E
    K --> E
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ビルドエラー | コンパイルエラー発生時 | エラー内容を確認し、ソースを修正 |
| - | ウォッチャーエラー | ファイルシステムエラー時 | watchプロセスを再起動 |
| - | メモリリーク | 長時間実行時 | プロセス再起動 |

### リトライ仕様

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

### 障害時対応

ビルドエラー時は監視プロセスは継続し、エラー内容がコンソールに出力される。開発者はエラーを確認してソースを修正し、再保存することで自動的に再ビルドが試行される。監視プロセス自体がハングした場合はCtrl+Cで終了し、再起動する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ファイル変更ごとに1回のビルド |
| 目標処理時間 | 変更検出から数秒以内にビルド開始 |
| メモリ使用量上限 | 500MB〜1GB（常駐プロセス） |

## 排他制御

ウォッチプロセスは1インスタンスのみ実行を推奨。複数のwatchプロセスが同時に実行されると、同一ファイルへの書き込み競合が発生する可能性がある。build-no-bundle-watchはメインプロセスでインクリメンタルビルドを実行する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | watch起動時 | 初回ビルド開始通知 |
| 検出ログ | ファイル変更検出時 | 変更されたファイルパス |
| 完了ログ | 各ビルド完了時 | ビルドタスク完了通知 |
| エラーログ | エラー発生時 | エラーメッセージ、スタックトレース |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| N/A | N/A | ローカル開発用のため監視対象外 |

## 備考

- build-no-bundle-watchはbuild-no-bundleと異なり、メインプロセスで実行される（useWorker: false）
- これによりインクリメンタルビルドが高速化される
- 監視対象のglobパターンはGulpfile.ts内のdefaultSourcesGlobおよび個別の監視設定で定義
- ヘルパーファイル（babel-helpers/src/helpers/*）は監視から除外されているソースグロブとは別に監視設定がある
- Ctrl+Cでグレースフルシャットダウンされる
