# バッチ設計書 12-build:watch:harmony

## 概要

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

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

このバッチは、`build:watch`のharmonyモード版です。Node.jsの`--harmony`フラグを有効にした状態でテストを実行することで、ES6以降の新機能（async/await、ジェネレーター等）を使用したコードのテストが可能になります。

**業務上の目的・背景**：CoffeeScriptはES6+の機能をサポートしており、これらの機能を使用したコードの開発・テストには、Node.jsのharmonyモードが必要な場合があります。特に、async/awaitやジェネレーター関数など、実験的または新しいJavaScript機能を使用するテストケースを開発する際に、このバッチを使用することで、ES6+機能を含むコードの継続的なビルド・テストが可能になります。

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

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

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

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

## バッチ種別

開発支援 / 継続的ビルド・テスト（ES6+機能テスト用）

## 実行スケジュール

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

## 実行条件

### 前提条件

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

### 実行可否判定

- `src/`および`test/`ディレクトリが存在すること
- `bin/coffee`および`bin/cake`が実行可能であること
- Node.jsが`--harmony`オプションをサポートしていること

## 入力仕様

### 入力パラメータ

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

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| 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, true)を呼び出し、パーサー含むフルビルドとharmonyテストを実行
2. ファイル監視開始
   └─ src/ディレクトリとtest/ディレクトリに対してfs.watchを設定
3. 変更検知ループ
   └─ changeイベント発生時にビルドとharmonyテストを再実行
4. src/配下の変更検知時
   └─ grammar.coffeeの場合はフルビルド、それ以外はパーサー除外ビルド
5. test/配下の変更検知時
   └─ パーサー除外ビルドとharmonyテスト実行
```

### フローチャート

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

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

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

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

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

該当なし

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

### 障害時対応

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

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

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

## パフォーマンス要件

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

## 排他制御

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

## ログ出力

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

## 監視・アラート

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

## 備考

- `build:watch`との唯一の違いは、テスト実行時に`--harmony`フラグが付与されること
- `watchAndBuildAndTest(yes)`として呼び出され、harmonyフラグがtrueに設定される
- ES6+機能（async/await、ジェネレーター、Proxy等）のテストに必要
- Node.jsのバージョンによっては、一部のharmony機能がデフォルトで有効になっている場合がある
