# 通知設計書 28-未捕捉例外出力

## 概要

本ドキュメントは、`@babel/cli`におけるプロセス全体の未捕捉例外（uncaughtException）を標準エラー出力に出力する機能の設計について記載する。

### 本通知の処理概要

この通知は、Babel CLIの実行中に発生した未捕捉の例外を捕捉し、エラー情報を標準エラー出力に出力し、プロセスの終了コードを1に設定するグローバルエラーハンドラ機能を提供する。

**業務上の目的・背景**：Node.jsプロセスでは、未捕捉の例外が発生するとプロセスがクラッシュする。この機能により、予期せぬエラーが発生した場合でもエラー情報を確実にユーザーに通知し、適切な終了コードでプロセスを終了させることができる。これはデバッグやCI/CDパイプラインでのエラー検出に重要である。

**通知の送信タイミング**：`process.on('uncaughtException', ...)`で登録されたハンドラが呼び出された際、つまりNode.jsランタイムが未捕捉の例外を検出した時点で、console.errorでエラーが出力される。

**通知の受信者**：Babel CLIを実行しているユーザー、ターミナルを監視している開発者、CI/CDパイプラインのログを監視している運用者が対象。

**通知内容の概要**：エラーオブジェクトがそのままconsole.errorに渡されるため、エラーメッセージとスタックトレースが出力される。

**期待されるアクション**：ユーザーは、エラーメッセージとスタックトレースを確認し、コードのバグを修正するか、Babelチームにバグレポートを提出することが期待される。

## 通知種別

コンソールエラー（console.error）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 最高 |
| リトライ | 無 |

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

標準エラー出力（stderr）に対してconsole.errorで出力される。エラーオブジェクト全体が出力されるため、スタックトレースも含まれる。

## 通知テンプレート

### コンソール出力

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr（console.error経由） |
| 形式 | Errorオブジェクト（スタックトレース含む） |

### 本文テンプレート

```
{Error.message}
{Error.stack}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | 添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| err | エラーオブジェクト | uncaughtExceptionイベントのパラメータ | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 未捕捉例外 | process uncaughtException イベント | 常に | プロセス内で未捕捉の例外が発生 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | 未捕捉例外が発生した場合は常にエラー出力される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[Babel CLIプロセス起動] --> B[uncaughtExceptionハンドラ登録]
    B --> C[通常処理]
    C --> D{未捕捉例外発生?}
    D -->|No| E[正常終了]
    D -->|Yes| F[uncaughtExceptionハンドラ呼び出し]
    F --> G[console.errorでエラー出力]
    G --> H[process.exitCode = 1]
    H --> I[プロセス終了]
    E --> I
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | データベースは使用しない |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | データベースは使用しない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 任意のError | コード内で未捕捉の例外が発生 | スタックトレースを確認してバグを修正 |
| TypeError | 型エラー | コードの型チェックを追加 |
| ReferenceError | 未定義変数の参照 | 変数定義を確認 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（例外発生時に同期的に出力）

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

- スタックトレースにローカルパスが含まれる
- 内部実装の詳細が漏洩する可能性がある
- 公開ログには注意が必要

## 備考

- このハンドラはutil.tsモジュールがロードされた時点で自動的に登録される
- Node.jsのuncaughtExceptionイベントは、デフォルトではプロセスを終了させる
- このハンドラにより、エラー情報を出力してから適切な終了コードで終了できる

---

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

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

### 推奨読解順序

#### Step 1: エラーハンドラの登録を理解する

uncaughtExceptionハンドラの登録部分を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | util.ts | `packages/babel-cli/src/babel/util.ts` | uncaughtExceptionハンドラ登録（120-123行目） |

**読解のコツ**: `process.on('uncaughtException', ...)`でグローバルなエラーハンドラを登録している。

#### Step 2: ハンドラの実装を理解する

ハンドラ内でのエラー処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | util.ts | `packages/babel-cli/src/babel/util.ts` | ハンドラ実装（120-123行目） |

**主要処理フロー**:
1. **行120**: `process.on("uncaughtException", function (err) { ... })`でハンドラ登録
2. **行121**: `console.error(err)`でエラー出力
3. **行122**: `process.exitCode = 1`で終了コードを設定

#### Step 3: モジュールの読み込みタイミングを理解する

util.tsがいつ読み込まれるかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | dir.ts | `packages/babel-cli/src/babel/dir.ts` | util.tsのimport（5行目） |
| 3-2 | file.ts | `packages/babel-cli/src/babel/file.ts` | util.tsのimport（7行目） |

**主要処理フロー**:
- CLIの起動時にdir.tsまたはfile.tsがロードされ、それに伴いutil.tsがロードされる
- util.tsのロード時にuncaughtExceptionハンドラが自動的に登録される

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

```
babel CLI 起動
    │
    ├─ dir.ts または file.ts ロード
    │      │
    │      └─ util.ts ロード
    │             │
    │             └─ process.on("uncaughtException", handler) 登録
    │
    └─ 通常処理...
           │
           ▼ (未捕捉例外発生)
    uncaughtExceptionハンドラ呼び出し
           │
           ├─ console.error(err)  ← エラー出力
           │
           └─ process.exitCode = 1
```

### データフロー図

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

未捕捉例外 ───▶ uncaughtException ハンドラ ───▶ エラー出力 + 終了コード1
                              │
                              ▼
                        console.error(err) ───▶ stderr（エラー情報）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| util.ts | `packages/babel-cli/src/babel/util.ts` | ソース | ユーティリティ関数とuncaughtExceptionハンドラ |
| dir.ts | `packages/babel-cli/src/babel/dir.ts` | ソース | ディレクトリコンパイル処理 |
| file.ts | `packages/babel-cli/src/babel/file.ts` | ソース | ファイルコンパイル処理 |
| index.ts | `packages/babel-cli/src/babel/index.ts` | ソース | CLIのエントリーポイント |
