# 通知設計書 2-コンパイル成功通知

## 概要

本ドキュメントは、Babel CLIでファイルのコンパイルが成功した際に、コンパイル結果をコンソールへ通知する機能について設計内容を記載する。

### 本通知の処理概要

この通知は、`babel` コマンドでディレクトリまたはファイルのコンパイルが完了した際に、コンパイルされたファイル数とコンパイル時間をユーザーに知らせる機能である。

**業務上の目的・背景**：開発者がBabelを使用してソースコードのトランスパイルを行う際、コンパイル処理が正常に完了したことを確認する必要がある。この通知により、ユーザーは何ファイルが処理されたか、どのくらいの時間がかかったかを把握でき、ビルドプロセスの正常性と効率性を確認できる。特にCIパイプラインやビルドスクリプトにおいて、成功通知は処理完了の確認に不可欠である。

**通知の送信タイミング**：すべてのファイルのコンパイル処理が完了した時点で送信される。ウォッチモードの場合は、ファイル変更検知後のコンパイルが完了するたびに通知される。debounce処理（100ms）により、連続したファイル変更がある場合は最後のコンパイル完了時にまとめて通知される。

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

**通知内容の概要**：「Successfully compiled X file(s) with Babel (Yms).」形式で、コンパイルされたファイル数と処理時間（ミリ秒）が出力される。

**期待されるアクション**：開発者は、この通知を受け取ることで、コンパイル処理が正常に完了したことを確認し、次の開発作業やデプロイ作業に進むことができる。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
Successfully compiled {compiledFiles} {fileWord} with Babel ({time}ms).
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| compiledFiles | コンパイルされたファイル数 | ローカル変数 compiledFiles | Yes |
| fileWord | "file" または "files"（複数形対応） | compiledFilesの値による条件分岐 | Yes |
| time | コンパイル処理時間（ミリ秒） | process.hrtime()の差分計算 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | ディレクトリ/ファイルコンパイル完了 | `--quiet`オプションが指定されていないこと | 初回ビルド完了時に通知 |
| ファイル変更 | ウォッチモードでの再コンパイル完了 | `--quiet`オプションが指定されていないこと、かつprocessing===0 | 変更検知後のコンパイル完了時に通知 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `--quiet`オプション指定 | 静音モードでは通知が抑制される |
| `--skipInitialBuild`オプション指定 | 初回ビルドスキップ時は通知されない |
| startTimeがnull | 時間計測が開始されていない場合は通知されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[babel コマンド実行] --> B[startTime = process.hrtime]
    B --> C[ファイルコンパイル処理]
    C --> D{全ファイル処理完了?}
    D -->|No| C
    D -->|Yes| E{--quiet指定?}
    E -->|Yes| F[通知スキップ]
    E -->|No| G[logSuccess呼び出し]
    G --> H[debounce待機 100ms]
    H --> I{startTime !== null?}
    I -->|Yes| J[処理時間計算]
    J --> K[console.log出力]
    K --> L[compiledFiles/startTimeリセット]
    I -->|No| M[処理終了]
    L --> M
    F --> M
```

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

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| startTimeがnull | 予期しない状態で通知が呼ばれた場合 | 通知処理を早期リターンしてクラッシュを防ぐ |

### リトライ仕様

リトライなし

## 配信設定

### レート制限

debounce処理により、100ms以内の連続コンパイルは集約される

### 配信時間帯

制限なし

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

特になし。コンパイル統計情報のみを出力するため、機密情報の漏洩リスクはない。

## 備考

- ファイル数が1件の場合は「file」、複数件の場合は「files」と出力される（英語の複数形対応）
- process.hrtime()を使用して高精度な時間計測を行っている
- debounce処理により、ウォッチモードでの連続変更時に通知が集約される

---

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

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

### 推奨読解順序

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

この通知に関わるデータ構造は、コンパイル結果を追跡するためのローカル変数である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | dir.ts | `packages/babel-cli/src/babel/dir.ts` | `compiledFiles`変数と`startTime`変数の宣言を確認（135-136行目） |

**読解のコツ**: `process.hrtime()`の戻り値は`[number, number]`型で、`[秒, ナノ秒]`の配列である。

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

コンパイル処理の開始から成功通知までの流れを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | dir.ts | `packages/babel-cli/src/babel/dir.ts` | default export関数全体の流れを確認 |

**主要処理フロー**:
1. **135-136行目**: `compiledFiles`と`startTime`変数の初期化
2. **138-154行目**: `logSuccess`関数の定義（debounce適用済み）
3. **165行目**: `startTime = process.hrtime()`で時間計測開始
4. **167-171行目**: ファイルコンパイルループ
5. **173-176行目**: `--quiet`でない場合に`logSuccess()`と`logSuccess.flush()`を呼び出し

#### Step 3: 通知関数の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | dir.ts | `packages/babel-cli/src/babel/dir.ts` | `logSuccess`関数の内部実装（138-154行目） |

**主要処理フロー**:
- **138行目**: `debounce`関数でラップ（100ms遅延）
- **139-143行目**: `startTime === null`のガード処理
- **145行目**: `process.hrtime(startTime)`で経過時間取得
- **147-151行目**: メッセージフォーマットとconsole.log出力
- **152-153行目**: `compiledFiles`と`startTime`のリセット

#### Step 4: ウォッチモードでの通知を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | dir.ts | `packages/babel-cli/src/babel/dir.ts` | ウォッチモードでの`onFilesChange`コールバック（234-250行目） |

**主要処理フロー**:
- **235-236行目**: `processing`カウンタのインクリメントと`startTime`設定
- **243行目**: `compiledFiles`の加算
- **248-249行目**: `processing === 0`かつ`--quiet`でない場合に`logSuccess()`呼び出し

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

```
babel CLI (main)
    │
    └─ dir.ts default export function
           │
           ├─ [初回ビルド]
           │      ├─ startTime = process.hrtime()
           │      ├─ handle() ループ
           │      │      └─ compiledFiles += count
           │      └─ logSuccess() → logSuccess.flush()
           │             └─ console.log(...)
           │
           └─ [ウォッチモード]
                  └─ watcher.onFilesChange(callback)
                         ├─ processing++
                         ├─ startTime設定
                         ├─ handleFile() → compiledFiles更新
                         ├─ processing--
                         └─ logSuccess()
                                └─ [debounce後] console.log(...)
```

### データフロー図

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

ソースファイル群 ───────▶ handle() / handleFile()
                                   │
                                   ▼
                           コンパイル実行
                                   │
                                   ▼
                           compiledFiles++
                                   │
                                   ▼
                           logSuccess() [debounce]
                                   │
                                   ▼
                           時間計算
                           diff[0]*1e3 + diff[1]/1e6 ───▶ stdout: "Successfully compiled..."
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dir.ts | `packages/babel-cli/src/babel/dir.ts` | ソース | ディレクトリモードのコンパイル処理と成功通知 |
| util.ts | `packages/babel-cli/src/babel/util.ts` | ソース | debounce関数の実装 |
| options.ts | `packages/babel-cli/src/babel/options.ts` | ソース | `--quiet`オプションの定義 |
| watcher.ts | `packages/babel-cli/src/babel/watcher.ts` | ソース | ファイル変更検知とコールバック管理 |
