# 機能設計書 4-@babel/generator

## 概要

本ドキュメントは、BabelのAST-to-codeジェネレーターである`@babel/generator`パッケージの設計仕様を記述する。このパッケージは、変換されたASTをJavaScriptソースコードに戻す機能を提供し、ソースマップ生成もサポートする。

### 本機能の処理概要

**業務上の目的・背景**：AST上でコード変換を行った後、最終的に実行可能なJavaScriptコードに変換する必要がある。@babel/generatorは、AST構造を走査して適切なJavaScriptコードを生成し、同時にソースマップを作成することで、デバッグ時の元のソースコードへのマッピングを可能にする。

**機能の利用シーン**：@babel/coreの変換パイプラインの最終段階で呼び出される場合、コード整形ツールでASTからコードを再生成する場合、ソースマップ付きのビルド成果物を生成する場合に利用される。

**主要な処理内容**：
1. ASTノードの再帰的な走査
2. 各ノードタイプに対応したコード文字列の生成
3. インデント・空白・改行の適切な挿入
4. コメントの元位置への復元
5. ソースマップの生成
6. compactモード、minifiedモード等の出力形式対応

**関連システム・外部連携**：@babel/core（変換パイプライン）、@babel/parser（元コード情報参照）、@jridgewell/gen-mapping（ソースマップ生成）と連携する。

**権限による制御**：特になし。純粋な文字列生成処理のみ。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本パッケージは画面との直接連携なし（内部API） |

## 機能種別

コード生成処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ast | t.Node | Yes | コード生成対象のAST | 有効なASTノード |
| opts | GeneratorOptions | No | 生成オプション | オブジェクト形式 |
| code | string \| Record<string, string> | No | 元ソースコード（ソースマップ用） | 文字列または複数ファイルマップ |

### GeneratorOptions

| パラメータ名 | 型 | 必須 | 説明 | デフォルト |
|-------------|-----|-----|------|---------|
| auxiliaryCommentBefore | string | No | 出力先頭に追加するブロックコメント | - |
| auxiliaryCommentAfter | string | No | 出力末尾に追加するブロックコメント | - |
| shouldPrintComment | Function | No | コメント出力判定関数 | - |
| experimental_preserveFormat | boolean | No | 元コードのフォーマット維持（実験的） | false |
| retainLines | boolean | No | 元ソースの行番号を維持 | false |
| retainFunctionParens | boolean | No | 関数式の括弧を維持 | false |
| comments | boolean | No | コメントを出力に含めるか | true |
| compact | boolean \| "auto" | No | 空白を削減（"auto"で500KB超で自動有効） | false |
| minified | boolean | No | 最小化出力 | false |
| concise | boolean | No | 軽度の空白削減 | false |
| filename | string | No | 警告メッセージ用ファイル名 | - |
| sourceMaps | boolean | No | ソースマップ生成 | false |
| inputSourceMap | any | No | 入力ソースマップ | - |
| sourceRoot | string | No | ソースマップのルートURL | - |
| sourceFileName | string | No | ソースマップのソースファイル名 | - |
| jsescOption | jsescOptions | No | 文字列エスケープオプション | - |
| topicToken | string | No | パイプライン演算子のトピックトークン | - |

### 入力データソース

- @babel/coreからの変換パイプライン
- プログラマティックな直接呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| code | string | 生成されたJavaScriptコード |
| map | EncodedSourceMap \| null | エンコードされたソースマップ |
| decodedMap | DecodedSourceMap \| undefined | デコードされたソースマップ |
| rawMappings | Mapping[] \| undefined | 生のマッピングデータ |

### 出力先

- @babel/coreへの返却
- 呼び出し元への直接返却

## 処理フロー

### 処理シーケンス

```
1. generate関数の呼び出し
   └─ AST、オプション、元コードを受け取る
2. オプションの正規化 (normalizeOptions)
   └─ デフォルト値適用
   └─ compact="auto"時の自動判定
3. SourceMapインスタンス生成（必要時）
4. Printerインスタンス生成
   └─ Format設定の適用
5. printer.generate(ast)実行
   └─ ASTの再帰的走査
   └─ 各ノードの出力
6. GeneratorResult構築
   └─ code、map、decodedMap、rawMappingsを返却
```

### フローチャート

```mermaid
flowchart TD
    A[generate呼び出し] --> B[normalizeOptions]
    B --> C{compact == "auto"?}
    C -->|Yes| D{code > 500KB?}
    D -->|Yes| E[compact = true]
    D -->|No| F[compact = false]
    C -->|No| G[指定値を使用]
    E --> H{sourceMaps?}
    F --> H
    G --> H
    H -->|Yes| I[SourceMap生成]
    H -->|No| J[map = null]
    I --> K[Printer生成]
    J --> K
    K --> L[printer.generate]
    L --> M[AST走査・コード生成]
    M --> N[GeneratorResult返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | compact自動判定 | compact="auto"で500KB超の場合、compactモードを有効化 | compact: "auto" |
| BR-02 | minified時のcompact | minified: trueの場合、compactも自動的にtrue | minified: true |
| BR-03 | コメント出力判定 | shouldPrintCommentまたはデフォルトロジックでコメント出力を判定 | comments: true |
| BR-04 | preserveFormat要件 | experimental_preserveFormat使用時はretainLinesとtokensが必須 | experimental_preserveFormat: true |
| BR-05 | 括弧の自動挿入 | 演算子優先順位に応じて必要な括弧を自動挿入 | 常時 |

### 計算ロジック

特になし

## データベース操作仕様

該当なし（メモリ内処理のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | オプションエラー | preserveFormat使用時に必須オプションが欠落 | 適切なオプション組み合わせを使用 |
| - | 生成エラー | 不明なノードタイプ | ジェネレーター関数の追加 |

### リトライ仕様

リトライ機能なし

## トランザクション仕様

該当なし（ステートレスな生成処理）

## パフォーマンス要件

- 大規模ファイル（500KB超）では自動的にcompactモードが有効化され、スタイリングが簡略化
- preserveFormat使用時はトークン情報が必要なため、パース時にtokens: trueが必須
- Bufferクラスによる効率的な文字列連結

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

- 入力ASTをそのままコード化するのみで、追加のコード注入は発生しない
- jsescOptionでUnicodeエスケープ方法を制御可能

## 備考

- experimental_preserveFormatは実験的機能であり、将来のマイナーバージョンで仕様変更の可能性あり
- JSXやTypeScript等の拡張構文も対応

---

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

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

### 推奨読解順序

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

まず、入出力のデータ構造を把握する。

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

**読解のコツ**: GeneratorOptionsの各オプションにはJSDocコメントで詳細説明がある。

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

処理の起点となるgenerate関数を確認する。

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

**主要処理フロー**:
1. **231-247行目**: generate関数のエントリーポイント
2. **236行目**: normalizeOptionsでオプション正規化
3. **237行目**: SourceMapインスタンス生成（必要時）
4. **239-244行目**: Printerインスタンス生成
5. **246行目**: printer.generateでコード生成

#### Step 3: オプション正規化を理解する

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

**主要処理フロー**:
- **24-55行目**: experimental_preserveFormatのバリデーション
- **57-80行目**: Formatオブジェクトの構築
- **82-94行目**: minified時の処理
- **96-105行目**: compact="auto"の自動判定（500KB閾値）

#### Step 4: Printerクラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | printer.ts | `packages/babel-generator/src/printer.ts` | Printerクラス、printメソッド |
| 4-2 | buffer.ts | `packages/babel-generator/src/buffer.ts` | Bufferクラス（文字列バッファ） |

#### Step 5: ノード別ジェネレーターを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | generators/index.ts | `packages/babel-generator/src/generators/index.ts` | ジェネレーター関数のエクスポート |
| 5-2 | generators/statements.ts | `packages/babel-generator/src/generators/statements.ts` | 文の生成（if, for, while等） |
| 5-3 | generators/expressions.ts | `packages/babel-generator/src/generators/expressions.ts` | 式の生成 |
| 5-4 | generators/classes.ts | `packages/babel-generator/src/generators/classes.ts` | クラスの生成 |
| 5-5 | generators/methods.ts | `packages/babel-generator/src/generators/methods.ts` | メソッドの生成 |
| 5-6 | generators/modules.ts | `packages/babel-generator/src/generators/modules.ts` | import/exportの生成 |
| 5-7 | generators/types.ts | `packages/babel-generator/src/generators/types.ts` | 型アノテーションの生成 |
| 5-8 | generators/typescript.ts | `packages/babel-generator/src/generators/typescript.ts` | TypeScript固有の生成 |
| 5-9 | generators/jsx.ts | `packages/babel-generator/src/generators/jsx.ts` | JSXの生成 |
| 5-10 | generators/flow.ts | `packages/babel-generator/src/generators/flow.ts` | Flow固有の生成 |

#### Step 6: ソースマップ生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | source-map.ts | `packages/babel-generator/src/source-map.ts` | SourceMapクラス |

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

```
generate (index.ts)
    │
    ├─ normalizeOptions
    │      └─ Format構築、compact自動判定
    │
    ├─ new SourceMap (source-map.ts)
    │      └─ @jridgewell/gen-mapping
    │
    └─ new Printer (printer.ts)
           │
           ├─ generate(ast)
           │      └─ print(node)
           │             └─ 再帰的にノード出力
           │
           ├─ Buffer (buffer.ts)
           │      └─ 文字列バッファ管理
           │
           └─ generators/*
                  ├─ statements.ts
                  ├─ expressions.ts
                  ├─ classes.ts
                  ├─ modules.ts
                  └─ ...
```

### データフロー図

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

AST (t.Node) ───────▶ Printer ───────▶ 生成コード
                          │                  (string)
元コード ───────▶ SourceMap ───────▶ ソースマップ
(string)           (位置情報追跡)       (EncodedSourceMap)

GeneratorOptions ───────▶ normalizeOptions ───────▶ Format
                                                   (内部設定)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-generator/src/index.ts` | ソース | 公開APIのエントリーポイント |
| printer.ts | `packages/babel-generator/src/printer.ts` | ソース | メインの出力ロジック |
| buffer.ts | `packages/babel-generator/src/buffer.ts` | ソース | 文字列バッファ管理 |
| source-map.ts | `packages/babel-generator/src/source-map.ts` | ソース | ソースマップ生成 |
| nodes.ts | `packages/babel-generator/src/nodes.ts` | ソース | ノード情報マップ |
| token-map.ts | `packages/babel-generator/src/token-map.ts` | ソース | トークンマップ（preserveFormat用） |
| node/index.ts | `packages/babel-generator/src/node/index.ts` | ソース | ノードユーティリティ |
| node/parentheses.ts | `packages/babel-generator/src/node/parentheses.ts` | ソース | 括弧必要性判定 |
| generators/index.ts | `packages/babel-generator/src/generators/index.ts` | ソース | ジェネレーターエクスポート |
| generators/base.ts | `packages/babel-generator/src/generators/base.ts` | ソース | 基本ノード生成 |
| generators/statements.ts | `packages/babel-generator/src/generators/statements.ts` | ソース | 文の生成 |
| generators/expressions.ts | `packages/babel-generator/src/generators/expressions.ts` | ソース | 式の生成 |
| generators/classes.ts | `packages/babel-generator/src/generators/classes.ts` | ソース | クラスの生成 |
| generators/methods.ts | `packages/babel-generator/src/generators/methods.ts` | ソース | メソッドの生成 |
| generators/modules.ts | `packages/babel-generator/src/generators/modules.ts` | ソース | モジュールの生成 |
| generators/types.ts | `packages/babel-generator/src/generators/types.ts` | ソース | 型の生成 |
| generators/typescript.ts | `packages/babel-generator/src/generators/typescript.ts` | ソース | TypeScriptの生成 |
| generators/jsx.ts | `packages/babel-generator/src/generators/jsx.ts` | ソース | JSXの生成 |
| generators/flow.ts | `packages/babel-generator/src/generators/flow.ts` | ソース | Flowの生成 |
| generators/template-literals.ts | `packages/babel-generator/src/generators/template-literals.ts` | ソース | テンプレートリテラルの生成 |
