# 通知設計書 3-ファイル変換通知

## 概要

本ドキュメントは、Babel CLIで個別ファイルの変換が完了した際に、変換の進捗をコンソールへ通知する機能について設計内容を記載する。この通知はverboseモード時のみ有効である。

### 本通知の処理概要

この通知は、`babel` コマンドに `--verbose` オプションを指定して実行した際に、各ファイルの変換進捗を個別に知らせる機能である。

**業務上の目的・背景**：開発者が大量のファイルをBabelで処理する際、どのファイルが処理されたかを把握したい場合がある。通常モードでは最終的なサマリーのみが表示されるが、verboseモードでは各ファイルの処理状況を詳細に確認できる。これはデバッグ時や、特定のファイルが正しく処理されているかを確認する際に有用である。また、処理に時間がかかる場合の進捗確認にも役立つ。

**通知の送信タイミング**：各ファイルのコンパイルが成功し、出力ファイルが書き込まれた直後に送信される。

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

**通知内容の概要**：「{入力ファイルパス} -> {出力ファイルパス}」形式で、変換元と変換先のファイルパスが出力される。

**期待されるアクション**：開発者は、この通知を見ることで、どのファイルが処理されたかをリアルタイムで確認できる。問題が発生した場合は、最後に出力されたファイルを手がかりにデバッグを行うことができる。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（console.log） |
| 優先度 | 低（デバッグ用） |
| リトライ | なし |

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
{relativeSrc} -> {dest}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| relativeSrc | 入力ファイルの相対パス | path.relative(process.cwd(), src) | Yes |
| dest | 出力ファイルの絶対パス | getDest()関数の戻り値 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | 個別ファイルのコンパイル成功 | `--verbose`オプションが指定されていること | 各ファイルの処理完了時に発火 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `--verbose`オプション未指定 | verboseモードでない場合は通知されない |
| コンパイル結果がnull | ファイルが無視された場合は通知されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[write関数呼び出し] --> B[拡張子チェック]
    B -->|非対応| C[NON_COMPILABLE返却]
    B -->|対応| D[util.compile実行]
    D --> E{コンパイル結果}
    E -->|null| F[IGNORED返却]
    E -->|成功| G[ソースマップ処理]
    G --> H[出力ファイル書き込み]
    H --> I[chmod設定]
    I --> J{--verbose指定?}
    J -->|Yes| K[console.log出力]
    J -->|No| L[通知スキップ]
    K --> M[COMPILED返却]
    L --> M
    C --> N[終了]
    F --> N
    M --> N
```

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

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| コンパイルエラー | Babel変換処理でエラー発生 | --watch時はエラー出力して継続、それ以外は例外スロー |

### リトライ仕様

リトライなし

## 配信設定

### レート制限

該当なし（各ファイルの処理完了時に都度出力）

### 配信時間帯

制限なし

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

ファイルパスが出力されるため、ディレクトリ構造が外部に漏洩する可能性がある。ただし、ローカル開発環境での使用を想定しているため、通常は問題とならない。

## 備考

- 入力ファイルパスはカレントディレクトリからの相対パスで表示される
- 出力ファイルパスは絶対パスで表示される
- この通知はディレクトリモード（dir.ts）でのみ使用され、ファイルモード（file.ts）では別の通知形式が使用される

---

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

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

### 推奨読解順序

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

この通知に関わるデータ構造は、ファイルパスとコンパイル結果である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | dir.ts | `packages/babel-cli/src/babel/dir.ts` | FILE_TYPEの定義（9-14行目）とwrite関数のシグネチャを確認 |

**読解のコツ**: `FILE_TYPE`はコンパイル結果の状態を表す列挙型的なオブジェクトで、`as const`により値が固定されている。

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

ファイル変換処理の流れを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | dir.ts | `packages/babel-cli/src/babel/dir.ts` | write関数（25-86行目）の全体構造を確認 |

**主要処理フロー**:
1. **29-33行目**: 拡張子チェックとNON_COMPILABLEの早期リターン
2. **44-48行目**: util.compile()でBabel変換を実行
3. **50行目**: 結果がnullの場合はIGNORED返却
4. **52-68行目**: ソースマップの処理
5. **70-71行目**: 出力ファイルの書き込みと権限設定
6. **73-75行目**: verboseモード時のconsole.log出力

#### Step 3: verbose条件の確認

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | dir.ts | `packages/babel-cli/src/babel/dir.ts` | cliOptions.verboseの条件チェック（73-75行目） |

**主要処理フロー**:
- **73行目**: `if (cliOptions.verbose)` でverboseモードを判定
- **74行目**: `path.relative(process.cwd(), src)` で相対パスを取得
- **74行目**: `dest`は変換先ファイルパス

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

```
babel CLI (main)
    │
    └─ dir.ts default export function
           │
           ├─ handle()
           │      └─ handleFile()
           │             └─ write()
           │                    │
           │                    ├─ util.isCompilableExtension()
           │                    │
           │                    ├─ util.compile()
           │                    │      └─ babel.transformFileAsync()
           │                    │
           │                    ├─ outputFileSync() [ファイル書き込み]
           │                    │
           │                    ├─ util.chmod()
           │                    │
           │                    └─ [verbose時] console.log(src -> dest)
           │
           └─ [ウォッチモード]
                  └─ watcher.onFilesChange(callback)
                         └─ handleFile()
                                └─ write()
                                       └─ [verbose時] console.log(...)
```

### データフロー図

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

src (入力ファイルパス) ───▶ write()
                                   │
                                   ▼
                           util.compile()
                                   │
                                   ▼
                           outputFileSync(dest, code)
                                   │
                                   ▼
                           [verbose && success]
                                   │
                                   ▼
path.relative(cwd, src)          console.log ───────▶ stdout: "src -> dest"
        +
      dest
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dir.ts | `packages/babel-cli/src/babel/dir.ts` | ソース | ディレクトリモードのコンパイル処理と通知 |
| util.ts | `packages/babel-cli/src/babel/util.ts` | ソース | compile関数、isCompilableExtension関数の実装 |
| options.ts | `packages/babel-cli/src/babel/options.ts` | ソース | `--verbose`オプションの定義 |
