# 帳票設計書 1-CodegenResult（render関数コード）

## 概要

本ドキュメントは、Vue.jsのcompiler-coreパッケージにおける`generate`関数が出力する`CodegenResult`（render関数コード）の設計仕様を記述する。テンプレートASTからJavaScriptのrender関数コードへの変換結果として生成されるデータ構造の全体像を示す。

### 本帳票の処理概要

compiler-coreの`generate`関数は、テンプレートAST（`RootNode`）を入力として受け取り、JavaScriptのrender関数コードを生成し、`CodegenResult`型のオブジェクトとして出力する。

**業務上の目的・背景**：Vueコンポーネントのテンプレート（HTML風の記述）をブラウザが実行可能なJavaScript render関数に変換する必要がある。この変換結果を構造化された形式で保持することで、後続のバンドルプロセスやHMR（Hot Module Replacement）で利用可能にする。

**帳票の利用シーン**：Vueコンポーネントのコンパイル時に、テンプレートからrender関数を生成する全ての場面で利用される。compiler-dom（クライアント向け）、compiler-ssr（サーバー向け）、compiler-sfc（SFCコンパイル）のいずれからも、最終的にこの`generate`関数を通じて`CodegenResult`が出力される。

**主要な出力内容**：
1. `code` - 生成されたJavaScript render関数コード文字列
2. `preamble` - setup()インラインモード時のプリアンブルコード（import文やhoisted変数宣言）
3. `ast` - 入力として受け取ったRootNode（変換済みAST）
4. `map` - ソースマップ（RawSourceMap、オプション）

**帳票の出力タイミング**：`baseCompile`関数の最終ステップとして、ASTのパースおよびトランスフォーム完了後に`generate`関数が呼び出され、CodegenResultが返される。

**帳票の利用者**：ビルドツール（Vite、webpack）、vue-loader、@vitejs/plugin-vue、およびVueのランタイムコンパイラ。

## 帳票種別

コード生成結果（データ構造出力）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | ビルドプロセス | - | テンプレートコンパイル実行時に自動生成 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JavaScript/TypeScript オブジェクト（インメモリ） |
| 用紙サイズ | 該当なし |
| 向き | 該当なし |
| ファイル名 | インメモリデータ（コンパイル結果として後続処理に渡される） |
| 出力方法 | 関数戻り値として返却 |
| 文字コード | UTF-8 |

### PDF固有設定

該当なし

### Excel固有設定

該当なし

## 帳票レイアウト

### レイアウト概要

CodegenResultは以下の4つのフィールドで構成されるオブジェクトである。

```
┌─────────────────────────────────────┐
│         CodegenResult               │
├─────────────────────────────────────┤
│  code: string                       │
│  （生成されたrender関数コード全体）    │
├─────────────────────────────────────┤
│  preamble: string                   │
│  （前文：import文・hoisted変数等）     │
├─────────────────────────────────────┤
│  ast: RootNode                      │
│  （変換済みテンプレートAST）           │
├─────────────────────────────────────┤
│  map?: RawSourceMap                 │
│  （ソースマップ、オプション）          │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | code | 生成されたrender関数のJavaScriptコード文字列 | CodegenContext.code | string |
| 2 | preamble | setup()インラインモード時のプリアンブル（空文字列の場合あり） | preambleContext.code | string |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | ast | 入力として渡されたRootNode（トランスフォーム済み） | generate関数の引数 | RootNode | - |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | map | ソースマップJSON（sourceMapオプション有効時のみ） | context.map.toJSON() | RawSourceMap / undefined |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| ast (RootNode) | テンプレートAST。パースおよびトランスフォーム済みであること | Yes |
| options (CodegenOptions) | コード生成オプション | No（デフォルト値あり） |

### ソート順

該当なし（単一オブジェクト出力のため）

### 改ページ条件

該当なし

## データベース参照仕様

### 参照テーブル一覧

該当なし（データベースアクセスなし。インメモリAST構造を処理）

### テーブル別参照項目詳細

該当なし

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| preamble | isSetupInlined ? preambleContext.code : "" | - | setup()インラインモード時のみプリアンブルが独立生成される |
| map | sourceMap ? context.map.toJSON() : undefined | - | sourceMapオプション有効時のみ生成 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[generate関数呼び出し] --> B[CodegenContext生成]
    B --> C{mode判定}
    C -->|module| D[genModulePreamble - ESM import文生成]
    C -->|function| E[genFunctionPreamble - グローバル変数宣言生成]
    D --> F[render関数シグネチャ生成]
    E --> F
    F --> G{SSR判定}
    G -->|SSR| H[ssrRender関数名・引数設定]
    G -->|クライアント| I[render関数名・引数設定]
    H --> J[AST codegenNodeからコード生成]
    I --> J
    J --> K[genNode再帰呼び出し]
    K --> L[CodegenResult構築]
    L --> M[code, preamble, ast, map を返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| codegenNodeなし | ast.codegenNodeがnull | DEVモードでassert警告 | トランスフォームを先に適用する |
| 未対応ノードタイプ | genNodeで未知のNodeTypeを処理 | unhandled codegen node type | DEVモードでassert（本番では無視） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1テンプレートにつき1回のgenerate呼び出し |
| 目標出力時間 | ミリ秒オーダー（テンプレートサイズに依存） |
| 同時出力数上限 | 制限なし（同期処理） |

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

生成されるコードはrender関数としてブラウザで実行されるため、テンプレート内のユーザー入力がそのままコードに埋め込まれないよう、`toDisplayString`ヘルパーを通じてエスケープ処理が行われる。ソースマップにはテンプレートのソースコードが含まれるため、本番ビルドではソースマップの公開範囲に注意が必要。

## 備考

- `generate`関数はcompiler-coreの中核機能であり、compiler-dom、compiler-ssr、compiler-sfcの全てがこの関数を経由してコードを生成する。
- `mode`オプションにより、`function`モード（ブラウザランタイムコンパイル用）と`module`モード（ビルドツール用ESM出力）の2つの出力形式を切り替える。
- `PURE_ANNOTATION`（`/*@__PURE__*/`）アノテーションは、tree-shakingを支援するために生成コードに付与される。

---

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

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

### 推奨読解順序

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

まず、CodegenResultの型定義と関連するデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | codegen.ts | `packages/compiler-core/src/codegen.ts` | CodegenResult型（108-113行目）、RawSourceMap型（83-91行目）、CodegenContext型（122-139行目）を確認 |
| 1-2 | ast.ts | `packages/compiler-core/src/ast.ts` | RootNode型の定義を確認。codegenNodeフィールドが最終的にコード生成の起点となる |
| 1-3 | options.ts | `packages/compiler-core/src/options.ts` | CodegenOptions型の定義を確認。generate関数の振る舞いを制御するオプション群 |

**読解のコツ**: CodegenResult型はわずか4フィールドだが、`code`フィールドに含まれるrender関数コードの構造を理解するには、`genNode`関数の再帰的なコード生成パターンを追う必要がある。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | codegen.ts | `packages/compiler-core/src/codegen.ts` | generate関数（283-406行目）がエントリーポイント |

**主要処理フロー**:
1. **289行目**: `createCodegenContext`でコンテキスト生成
2. **302行目**: `ast.helpers`からヘルパー関数リストを取得
3. **314-318行目**: モードに応じてpreamble（前文）を生成
4. **320-321行目**: SSR/クライアントに応じて関数名・引数を設定
5. **386-390行目**: `genNode`でAST codegenNodeからコードを再帰生成
6. **400-405行目**: CodegenResultオブジェクトを構築して返却

#### Step 3: コンテキスト生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | codegen.ts | `packages/compiler-core/src/codegen.ts` | createCodegenContext関数（141-281行目）でソースマップ生成器やpush/indent/deindentユーティリティを初期化 |

**主要処理フロー**:
- **158-250行目**: contextオブジェクトの生成。push関数はコードの追記とソースマップのマッピングを同時に行う
- **272-278行目**: sourceMapオプション有効時にSourceMapGeneratorを初期化

#### Step 4: コード生成（genNode）の再帰処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | codegen.ts | `packages/compiler-core/src/codegen.ts` | genNode関数（650-745行目）がNodeTypeに応じて各生成関数にディスパッチ |
| 4-2 | codegen.ts | `packages/compiler-core/src/codegen.ts` | genVNodeCall（817-878行目）がVNodeの生成コードを出力する中核ロジック |

**主要処理フロー**:
- **659-744行目**: switch文でNodeTypeに応じた生成関数を呼び出す
- **817-878行目**: `genVNodeCall`でcreateVNode/createBlockの呼び出しコードを生成
- **1046-1064行目**: `genTemplateLiteral`でSSR用のテンプレートリテラルを生成

#### Step 5: 上位呼び出し元を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | compile.ts | `packages/compiler-core/src/compile.ts` | baseCompile関数（67-122行目）がparse -> transform -> generateの3ステップを実行 |

**主要処理フロー**:
- **95行目**: ソースをパースしてASTを生成
- **106-119行目**: ASTにトランスフォームを適用
- **121行目**: `generate(ast, resolvedOptions)`でCodegenResultを生成して返却

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

```
baseCompile (compile.ts:67)
    |
    +-- baseParse (parser.ts) ... テンプレート文字列 -> RootNode
    |
    +-- transform (transform.ts) ... RootNode にトランスフォーム適用
    |
    +-- generate (codegen.ts:283) ... RootNode -> CodegenResult
            |
            +-- createCodegenContext (codegen.ts:141)
            |       +-- new SourceMapGenerator() (sourceMap有効時)
            |
            +-- genModulePreamble (codegen.ts:470) / genFunctionPreamble (codegen.ts:408)
            |       +-- genHoists (codegen.ts:567)
            |       +-- genImports (codegen.ts:587)
            |
            +-- genNode (codegen.ts:650) ... 再帰的コード生成
                    +-- genVNodeCall (codegen.ts:817)
                    +-- genCallExpression (codegen.ts:889)
                    +-- genObjectExpression (codegen.ts:900)
                    +-- genConditionalExpression (codegen.ts:979)
                    +-- genCacheExpression (codegen.ts:1015)
                    +-- genTemplateLiteral (codegen.ts:1046) [SSR]
                    +-- genIfStatement (codegen.ts:1066) [SSR]
```

### データフロー図

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

テンプレートAST      ──▶  createCodegenContext     ──▶  CodegenContext
(RootNode)                      |
                          genPreamble              ──▶  preambleコード
                                |
                          genNode(再帰)            ──▶  render関数本体コード
                                |
                          SourceMapGenerator       ──▶  RawSourceMap
                                |
                          ────────────────────────────▶  CodegenResult
                                                          { code, preamble, ast, map }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| codegen.ts | `packages/compiler-core/src/codegen.ts` | ソース | CodegenResult型定義、generate関数、genNode等のコード生成ロジック |
| compile.ts | `packages/compiler-core/src/compile.ts` | ソース | baseCompile関数（generate呼び出し元） |
| options.ts | `packages/compiler-core/src/options.ts` | ソース | CodegenOptions型定義 |
| ast.ts | `packages/compiler-core/src/ast.ts` | ソース | RootNode、各ノードタイプの型定義 |
| runtimeHelpers.ts | `packages/compiler-core/src/runtimeHelpers.ts` | ソース | helperNameMapによるランタイムヘルパー名のマッピング |
| transform.ts | `packages/compiler-core/src/transform.ts` | ソース | ImportItem型定義、transform関数 |
| utils.ts | `packages/compiler-core/src/utils.ts` | ソース | advancePositionWithMutation、isSimpleIdentifier等のユーティリティ |
