# 通知設計書 38-compilation success

## 概要

本ドキュメントは、CoffeeScriptコンパイラでファイルのコンパイルが成功した際に表示される情報通知「compilation success」の設計仕様を記載する。

### 本通知の処理概要

CoffeeScriptのCLI（`coffee`コマンド）で`--compile`オプションと`--watch`オプションを併用した際、ファイルのコンパイルが成功するたびにタイムスタンプ付きのログメッセージを標準出力に表示する通知機能である。

**業務上の目的・背景**：ファイル監視モードでは、ソースファイルの変更を検出して自動的に再コンパイルが行われる。開発者は複数のファイルを同時に編集しながら作業することが多いため、どのファイルがいつコンパイルされたかを視覚的に確認できることが重要である。この通知により、開発者は変更が正しく反映されたことを確認できる。

**通知の送信タイミング**：`--watch`モードでファイルが正常にコンパイルされ、`.js`ファイルがファイルシステムに書き込まれた直後に通知される。

**通知の受信者**：コマンドラインでCoffeeScriptコンパイラをwatch モードで実行している開発者。標準出力（stdout）に出力されるため、ターミナルに表示される。

**通知内容の概要**：「{タイムスタンプ} - compiled {ソースファイルパス}」の形式でログメッセージを出力する。タイムスタンプはローカルタイムゾーンの時刻を使用する。

**期待されるアクション**：特に必要なアクションはない。開発者はこのメッセージを確認することで、ファイル変更が検出されコンパイルが完了したことを認識できる。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（fs.writeFileコールバック後） |
| 優先度 | 低（情報通知） |
| リトライ | 無し |

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

標準出力（stdout）への直接出力のため、受信者決定ロジックは不要。コマンド実行元のターミナルに出力される。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | stdout（console.log経由のtimeLog関数） |
| 形式 | テキスト |

### 本文テンプレート

```
{timestamp} - compiled {sourcePath}
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| timestamp | ローカル時刻のタイムスタンプ | new Date().toLocaleTimeString() | Yes |
| sourcePath | コンパイル元のソースファイルパス | writeJs関数の引数 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ファイル変更検出 | fs.writeFile成功コールバック | opts.compile && opts.watch | watchモードでのコンパイル成功 |

### 前提条件

| 条件 | 説明 |
|-----|------|
| opts.compile === true | --compileオプションが指定されている |
| opts.watch === true | --watchオプションが指定されている |
| fs.writeFileが成功 | JavaScriptファイルの書き込みが正常完了 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| opts.watchがfalse | watchモードでない場合は通知されない |
| fs.writeFileでエラー | 書き込みエラーの場合は別のエラー処理が行われる |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[watchモードでファイル変更検出] --> B[compile関数実行]
    B --> C[CoffeeScript.compile成功]
    C --> D[writeJs関数呼び出し]
    D --> E[fs.writeFile jsPath]
    E --> F{書き込み成功?}
    F -->|No| G[エラー処理]
    F -->|Yes| H{opts.compile && opts.watch?}
    H -->|No| I[処理終了]
    H -->|Yes| J[timeLog compiled sourcePath]
    J --> I
```

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

### 参照テーブル一覧

なし

### ファイルシステム操作

| 操作 | 関数 | 目的 |
|-----|------|------|
| ファイル書き込み | fs.writeFile | JavaScriptファイルの保存 |

### 更新テーブル一覧

なし

## エラー処理

### エラーケース一覧

この通知は成功時のみ表示されるため、エラーケースはなし。

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

なし（ファイル変更検出ごとに表示）

### 配信時間帯

制限なし（watchモード実行中は継続的に監視）

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

- ソースファイルパスがログに出力されるため、機密性の高いパス情報が表示される可能性がある
- ローカル環境での開発用途が主であり、セキュリティリスクは低い

## 備考

- timeLog関数はタイムスタンプを`new Date().toLocaleTimeString()`で生成するため、ロケール設定に依存した形式で表示される
- `--watch`オプションなしでの単発コンパイルでは、この通知は表示されない
- 複数ファイルの同時変更時は、各ファイルのコンパイル完了ごとに個別にログが出力される

---

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

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

### 推奨読解順序

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

ログ出力に関連する関数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | command.coffee | `src/command.coffee` | timeLog関数（432-433行目）を確認 |
| 1-2 | command.coffee | `src/command.coffee` | SWITCHES配列（55行目: -w, --watch）を確認 |

**読解のコツ**: timeLogはconsole.logのラッパーで、タイムスタンプを付加することを理解する。

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

処理の起点となる関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | command.coffee | `src/command.coffee` | writeJs関数（407-426行目）でログ出力を確認 |

**主要処理フロー**:
1. **407行目**: `writeJs = (base, sourcePath, js, jsPath, generatedSourceMap = null) ->`
2. **414-419行目**: fs.writeFileによるJavaScript書き込み
3. **418-419行目**: 成功時のtimeLog呼び出し

#### Step 3: ログ出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | command.coffee | `src/command.coffee` | 418-419行目でのログ出力条件を確認 |

**主要処理フロー**:
- **414行目**: `fs.writeFile jsPath, js, (err) ->`
- **415-417行目**: エラー処理
- **418行目**: `else if opts.compile and opts.watch`
- **419行目**: `timeLog "compiled #{sourcePath}"`

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

```
watch (command.coffee:274)
    │
    └─ compile (内部関数:289)
           │
           └─ compileScript (command.coffee:202)
                  │
                  └─ writeJs (command.coffee:407)
                         │
                         └─ fs.writeFile
                                │
                                └─ [成功 && opts.compile && opts.watch]
                                       └─ timeLog "compiled #{sourcePath}"
```

### データフロー図

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

ファイル変更検出 ───▶ compileScript() ───▶ writeJs()
                                                │
                                                ▼
                                          fs.writeFile()
                                                │
                                                ▼
                                          [成功時]
                                                │
                                                ▼
                           [opts.compile && opts.watch]
                                                │
                                                ▼
                                          timeLog()
                                                │
                                                ▼
                     console.log("{timestamp} - compiled {sourcePath}")
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| command.coffee | `src/command.coffee` | ソース | CLIエントリーポイント、ファイル監視、ログ出力 |
