# バッチ設計書 11-build:watch

## 概要

本ドキュメントは、CoffeeScriptプロジェクトにおける`build:watch`タスクの設計書です。このバッチは、ソースファイルの変更を監視し、変更を検知した際に自動的にリビルドとテスト実行を行う開発支援ツールです。

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

このバッチは、CoffeeScriptコンパイラの開発中に使用される継続的ビルド・テストツールです。ソースコードやテストファイルの変更をリアルタイムで監視し、変更が検知されると自動的にコンパイラをリビルドしてテストを実行します。

**業務上の目的・背景**：CoffeeScriptコンパイラの開発において、ソースコードを変更するたびに手動でビルドとテストを実行するのは非効率です。このバッチを使用することで、開発者はコードの編集に集中でき、保存するだけで自動的にビルドとテストが実行されるため、開発サイクルを大幅に短縮できます。即座にフィードバックを得られることで、バグの早期発見と修正が可能になります。

**バッチの実行タイミング**：開発者が手動で起動し、開発セッション中は継続的に実行されます。ソースファイル（`src/`ディレクトリ）またはテストファイル（`test/`ディレクトリ）に変更が発生した際に、自動的にビルドとテストが実行されます。

**主要な処理内容**：
1. 初回起動時に完全ビルド（パーサー含む）とテストを実行
2. `src/`ディレクトリの変更を200ms間隔で監視
3. `test/`ディレクトリの変更を200ms間隔で再帰的に監視
4. `grammar.coffee`が変更された場合はパーサーを含むフルビルドを実行
5. その他のソースファイル変更時はパーサーを除いたビルドを実行
6. テストファイル変更時はパーサーを除いたビルドを実行
7. 各ビルド後にテストスイートを自動実行

**前後の処理との関連**：このバッチは`build`タスクと`build:except-parser`タスク、および`test`タスクを内部的に呼び出します。事前に`npm install`による依存関係のインストールが完了している必要があります。

**影響範囲**：`lib/coffeescript/`ディレクトリ配下のコンパイル済みJavaScriptファイルが更新されます。テスト実行結果がコンソールに出力されます。

## バッチ種別

開発支援 / 継続的ビルド・テスト

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（開発時） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動起動後、ファイル変更イベント |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.jsがインストールされていること |
| 依存パッケージ | `npm install`が完了していること |
| Gitリポジトリ | `lib/*`がgit管理下にあること（リセット用） |

### 実行可否判定

- `src/`および`test/`ディレクトリが存在すること
- `bin/coffee`および`bin/cake`が実行可能であること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | コマンドライン引数なし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| src/*.coffee | CoffeeScript | コンパイラソースファイル |
| src/*.litcoffee | Literate CoffeeScript | 文芸的CoffeeScriptソースファイル |
| test/*.coffee | CoffeeScript | テストファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| lib/coffeescript/*.js | JavaScript | コンパイル済みファイル |
| lib/coffeescript/parser.js | JavaScript | Jisonパーサー |
| 標準出力 | テキスト | ビルド・テスト結果 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 元のCoffeeScriptファイル名.js |
| 出力先 | lib/coffeescript/ |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. 初期ビルド実行
   └─ buildAndTest(true, false)を呼び出し、パーサー含むフルビルドとテストを実行
2. ファイル監視開始
   └─ src/ディレクトリとtest/ディレクトリに対してfs.watchを設定
3. 変更検知ループ
   └─ changeイベント発生時にビルドとテストを再実行
4. src/配下の変更検知時
   └─ grammar.coffeeの場合はフルビルド、それ以外はパーサー除外ビルド
5. test/配下の変更検知時
   └─ パーサー除外ビルドとテスト実行
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[初期ビルド実行]
    B --> C[テスト実行]
    C --> D[ファイル監視開始]
    D --> E{変更検知?}
    E -->|なし| E
    E -->|src/変更| F{grammar.coffee?}
    F -->|はい| G[フルビルド]
    F -->|いいえ| H[パーサー除外ビルド]
    E -->|test/変更| H
    G --> I[テスト実行]
    H --> I
    I --> E
```

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

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

該当なし（ファイルシステム操作のみ）

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | コンパイルエラー | CoffeeScriptの構文エラー | ソースファイルを修正 |
| 1 | テスト失敗 | テストケースが失敗 | テストまたはソースを修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（次のファイル変更時に再実行） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

- コンパイルエラー発生時：エラーメッセージを確認し、ソースファイルを修正して保存すると自動的に再ビルドされる
- プロセス停止時：`cake build:watch`で再起動

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | git checkout lib/*で初期状態にリセット |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ソースファイル約10個 |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

- 同時実行：不可（同一ディレクトリで複数起動すべきでない）
- ロック仕様：なし

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ビルド開始時 | "building..." または "building, including parser..." |
| 進捗ログ | 変更検知時 | "src/filename changed, rebuilding..." |
| 終了ログ | テスト完了時 | テスト結果サマリー |
| エラーログ | エラー発生時 | コンパイルエラーまたはテスト失敗の詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 該当なし | - | - |

## 備考

- 監視間隔は200msに設定されており、頻繁な保存に対応
- 画面クリア（`\x1Bc`）により、各ビルドサイクルでクリーンな出力を表示
- `test/`ディレクトリは再帰的に監視される（`recursive: yes`オプション）
- harmonyモードでの実行が必要な場合は`build:watch:harmony`を使用
