# 通知設計書 23-コードジェネレータエラー警告

## 概要

本ドキュメントは、`@babel/generator`におけるコード生成時に、大きなファイルサイズを検出した際に出力されるコードジェネレータエラー警告（deoptimisation警告）の設計について記載する。

### 本通知の処理概要

この通知は、Babelがコード生成を行う際に、対象のソースコードが500KBを超える大きなファイルである場合に、スタイリング（整形）の最適化を無効化したことをユーザーに通知する機能を提供する。

**業務上の目的・背景**：大きなファイルに対してコードの整形処理を行うと、メモリ使用量が増加し、処理時間が長くなる可能性がある。このため、`compact`オプションが`"auto"`に設定されている場合、500KBを超えるファイルでは自動的にcompactモードが有効化される。この警告により、開発者はスタイリングが変更されたことを認識し、必要に応じて設定を調整できる。

**通知の送信タイミング**：`normalizeOptions`関数内で`compact`オプションが`"auto"`に設定されており、かつソースコードのサイズが500KBを超えた場合に、コード生成処理の初期化時に警告が出力される。

**通知の受信者**：コンソールを監視している開発者、特にBabelを使用してコード変換を行っている開発者が対象。

**通知内容の概要**：警告メッセージには、対象のファイル名と、500KBの制限を超えたためにスタイリングが最適化解除されたことが含まれる。

**期待されるアクション**：開発者は、警告の内容を確認し、大きなファイルをより小さなモジュールに分割するか、明示的に`compact: true`または`compact: false`を設定して警告を抑制するか、またはそのまま続行するかを判断することが期待される。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

標準エラー出力（stderr）に対してconsole.errorで出力される。Babelのコード生成処理を実行しているプロセスのコンソールに表示される。

## 通知テンプレート

### コンソール出力

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr（console.error経由） |
| 形式 | プレーンテキスト |

### 本文テンプレート

```
[BABEL] Note: The code generator has deoptimised the styling of ${filename} as it exceeds the max of 500KB.
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| filename | 対象のファイル名 | opts.filename（GeneratorOptions） | No（未指定時は空文字列相当） |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 処理中 | normalizeOptions関数の呼び出し | compact === "auto" かつ code.length > 500_000 | コード生成の初期化処理時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| compactがtrueまたはfalseに明示的に設定されている | auto以外の場合はサイズチェックを行わない |
| コードサイズが500KB以下 | 閾値を超えない場合は警告なし |
| codeが文字列でない | codeがRecord<string, string>の場合はサイズチェックをスキップ |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[generate関数呼び出し] --> B[normalizeOptions関数呼び出し]
    B --> C{format.compact === "auto"?}
    C -->|No| D[通常処理を継続]
    C -->|Yes| E{typeof code === "string"?}
    E -->|No| D
    E -->|Yes| F{code.length > 500_000?}
    F -->|No| G[format.compact = false]
    F -->|Yes| H[format.compact = true]
    H --> I[console.errorで警告出力]
    G --> D
    I --> D
    D --> J[コード生成実行]
    J --> K[終了]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | - | 警告出力のみでエラーは発生しない |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし（ファイルごとに1回出力） |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（コード生成時に同期的に出力）

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

- ファイル名が出力されるが、これはビルドプロセスの一部であり通常は機密情報ではない
- ローカルファイルパスが出力される可能性があるため、公開ログには注意が必要

## 備考

- 500KBの閾値はハードコードされており、設定で変更することはできない
- この警告は「Note」として出力されており、エラーではないことを示している
- compactモードが有効になると、出力コードの空白や改行が最小化される

---

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

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

### 推奨読解順序

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

まず、GeneratorOptionsの型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-generator/src/index.ts` | GeneratorOptions型の定義（124-215行目） |

**読解のコツ**: `compact`オプションが`boolean | "auto"`型であることを確認する（170行目）。

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

警告を出力するnormalizeOptions関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-generator/src/index.ts` | normalizeOptions関数の実装（19-122行目） |

**主要処理フロー**:
1. **行57-80**: Formatオブジェクトの初期化
2. **行96-105**: compactがautoの場合のサイズチェック処理
3. **行97**: 文字列かつ500KB超のチェック
4. **行99-103**: 警告メッセージの出力

#### Step 3: generate関数を理解する

generate関数がどのようにnormalizeOptionsを呼び出すかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-generator/src/index.ts` | generate関数（231-247行目） |

**主要処理フロー**:
- **行236**: normalizeOptions関数の呼び出し

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

```
呼び出し元（@babel/core等）
    │
    └─ generate(ast, opts, code)
           │
           └─ normalizeOptions(code, opts, ast)
                  │
                  ├─ Format オブジェクト作成
                  │
                  └─ compact === "auto" の場合
                         │
                         ├─ code.length > 500_000
                         │      └─ console.error(message)  ← 警告出力
                         │
                         └─ format.compact = true/false を設定
```

### データフロー図

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

AST, オプション, コード ───▶ generate関数 ───▶ GeneratorResult
                              │
                              ▼
                        normalizeOptions
                              │
                              ▼ (compact === "auto")
                        サイズチェック ───▶ console.error（警告メッセージ）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-generator/src/index.ts` | ソース | コード生成のエントリーポイントと警告出力 |
| printer.ts | `packages/babel-generator/src/printer.ts` | ソース | 実際のコード出力処理 |
| source-map.ts | `packages/babel-generator/src/source-map.ts` | ソース | ソースマップ生成 |
