# 通知設計書 1-ウォッチャー準備完了通知

## 概要

本ドキュメントは、Babel CLIのファイル監視モード（`--watch`オプション）において、ウォッチャーの準備が完了した際にコンソールへ通知を行う機能について設計内容を記載する。

### 本通知の処理概要

この通知は、`babel` コマンドに `--watch` オプションを指定して実行した際に、ファイル監視の準備が整ったことをユーザーに知らせる機能である。

**業務上の目的・背景**：開発者がBabelを使用してJavaScript/TypeScriptのトランスパイルを行う際、`--watch`モードを使用することでファイル変更を自動検知し、再コンパイルを行う。ウォッチャーの準備完了通知は、ユーザーがコマンド実行後にシステムが正常に起動し、ファイル監視が開始されたことを確認するために必要である。この通知がなければ、ユーザーはシステムがハングアップしているのか、正常に動作しているのか判断できない。

**通知の送信タイミング**：chokidarライブラリによるファイルウォッチャーが初期化され、監視対象ファイルの初回スキャンが完了した時点で「ready」イベントが発火する。このイベントをトリガーとして通知が送信される。

**通知の受信者**：コマンドを実行した開発者（標準出力を監視しているユーザー）

**通知内容の概要**：「The watcher is ready.」という固定メッセージが標準出力に出力される。

**期待されるアクション**：開発者は、この通知を受け取ることで、ファイル監視が正常に開始されたことを確認し、監視対象ファイルの編集作業を安心して開始できる。

## 通知種別

コンソール出力（標準出力：stdout）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（console.log） |
| 優先度 | 中 |
| リトライ | なし |

### 送信先決定ロジック

標準出力（stdout）に固定。特定の送信先決定ロジックはなく、プロセスの標準出力に直接出力される。

## 通知テンプレート

### コンソール通知の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | 標準出力（stdout） |
| フォーマット | プレーンテキスト |

### 本文テンプレート

```
The watcher is ready.
```

### 添付ファイル

該当なし

## テンプレート変数

該当なし（固定メッセージ）

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | chokidar FSWatcherの「ready」イベント | `--watch`オプションが指定されていること | ファイルウォッチャーの初期化完了時に発火 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `--watch`オプション未指定 | ウォッチモードでない場合は、ウォッチャー自体が起動しないため通知は行われない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[babel --watch コマンド実行] --> B[watcher.enable呼び出し]
    B --> C[FSWatcher インスタンス生成]
    C --> D[対象ファイル/ディレクトリの監視開始]
    D --> E[watcher.startWatcher呼び出し]
    E --> F[readyイベントリスナー登録]
    F --> G{ファイルスキャン完了?}
    G -->|完了| H[readyイベント発火]
    H --> I[console.log出力]
    I --> J[監視継続]
    G -->|未完了| G
```

## データベース参照・更新仕様

該当なし（データベースを使用しない）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| chokidarインストール失敗 | chokidarライブラリが見つからない場合 | エラーメッセージを標準エラー出力に表示し、例外をスローする |

### リトライ仕様

リトライなし

## 配信設定

### レート制限

該当なし（ウォッチャー起動時に1回のみ出力）

### 配信時間帯

制限なし（コマンド実行時のみ）

## セキュリティ考慮事項

特になし。固定メッセージのみを出力するため、機密情報の漏洩リスクはない。

## 備考

- この通知は chokidar ライブラリの `ready` イベントに依存している
- chokidar はオプショナルな依存関係として定義されており、インストールされていない場合は専用のエラーメッセージが表示される

---

## コードリーディングガイド

本通知を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

この通知に関わるデータ構造は比較的シンプルで、主にchokidarのFSWatcherインスタンスに関するものである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | watcher.ts | `packages/babel-cli/src/babel/watcher.ts` | FSWatcherインスタンスの宣言と、監視キュー（watchQueue）の構造を確認する |

**読解のコツ**: TypeScriptの型インポート（`type FSWatcher`）を追跡すると、chokidarライブラリの型定義が参照されていることがわかる。

#### Step 2: エントリーポイントを理解する

監視モードの起動は、dir.tsまたはfile.tsから開始される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | dir.ts | `packages/babel-cli/src/babel/dir.ts` | ディレクトリモードでの `--watch` オプション処理を確認 |
| 2-2 | file.ts | `packages/babel-cli/src/babel/file.ts` | ファイルモードでの `--watch` オプション処理を確認 |

**主要処理フロー**:
1. **dir.ts:156行目**: `cliOptions.watch` が true の場合、`watcher.enable()` を呼び出す
2. **dir.ts:231行目**: `watcher.startWatcher()` を呼び出してウォッチャーを起動する

#### Step 3: ウォッチャー初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | watcher.ts | `packages/babel-cli/src/babel/watcher.ts` | `enable()` 関数と `startWatcher()` 関数の実装を確認 |

**主要処理フロー**:
- **13-30行目**: `enable()` 関数でFSWatcherインスタンスを生成
- **32-43行目**: `startWatcher()` 関数で監視を開始し、readyイベントリスナーを登録
- **40-42行目**: readyイベント発火時に `console.log("The watcher is ready.")` を実行

### プログラム呼び出し階層図

```
babel CLI (main)
    │
    ├─ dir.ts default export function
    │      │
    │      ├─ watcher.enable()
    │      │      └─ FSWatcher インスタンス生成
    │      │
    │      ├─ watcher.watch()
    │      │      └─ 監視対象ファイル追加
    │      │
    │      └─ watcher.startWatcher()
    │             └─ watcher.on("ready", callback)
    │                    └─ console.log("The watcher is ready.")
    │
    └─ file.ts default export function
           └─ (同様の構造)
```

### データフロー図

```
[入力]                       [処理]                           [出力]

--watch オプション ───────▶ dir.ts / file.ts
                                   │
                                   ▼
                           watcher.enable()
                                   │
                                   ▼
                           FSWatcher生成
                                   │
                                   ▼
                           watcher.startWatcher()
                                   │
                                   ▼
                           readyイベント待機
                                   │
                                   ▼
                           readyイベント発火 ───────▶ stdout: "The watcher is ready."
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| watcher.ts | `packages/babel-cli/src/babel/watcher.ts` | ソース | ウォッチャーの中核実装。通知処理を含む |
| dir.ts | `packages/babel-cli/src/babel/dir.ts` | ソース | ディレクトリモードでのBabel CLI実行処理 |
| file.ts | `packages/babel-cli/src/babel/file.ts` | ソース | ファイルモードでのBabel CLI実行処理 |
| options.ts | `packages/babel-cli/src/babel/options.ts` | ソース | CLIオプションの定義と解析 |
