# 帳票設計書 2-DOMコンパイル結果

## 概要

本ドキュメントは、Vue.jsのcompiler-domパッケージにおける`compile`関数が出力するDOMコンパイル結果（`CodegenResult`）の設計仕様を記述する。DOM向けテンプレートをコンパイルし、クライアントサイド用のrender関数コードを生成する。

### 本帳票の処理概要

compiler-domの`compile`関数は、テンプレート文字列またはRootNodeを入力として受け取り、DOMNodeTransformsおよびDOMDirectiveTransformsを適用した上でクライアントサイド用のrender関数コードを生成し、`CodegenResult`として出力する。

**業務上の目的・背景**：ブラウザ上で動作するVueコンポーネントは、テンプレートをDOM操作に最適化されたrender関数に変換する必要がある。compiler-domはcompiler-coreのbaseCompileをラップし、DOM固有のトランスフォーム（v-html、v-text、v-model、v-on、v-show等）やHTMLバリデーション（ネスティング検証）を追加して、ブラウザ実行に適したコードを生成する。

**帳票の利用シーン**：Vueコンポーネントのテンプレートをクライアントサイド向けにコンパイルする全ての場面。ビルドツール経由のプリコンパイルと、ブラウザ上でのランタイムコンパイルの両方で使用される。

**主要な出力内容**：
1. `code` - DOM操作に最適化されたrender関数コード
2. `preamble` - setup()インラインモード時のプリアンブル
3. `ast` - トランスフォーム済みのRootNode
4. `map` - ソースマップ（オプション）

**帳票の出力タイミング**：ビルド時（Vite/webpack）またはランタイム時にテンプレートが検出された際に`compile`関数が呼び出される。

**帳票の利用者**：ビルドツール（Vite、webpack）のVueプラグイン、ランタイムコンパイラ、compiler-sfc（SFCのtemplate部コンパイル時のデフォルトコンパイラ）。

## 帳票種別

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

## 利用画面

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

## 出力形式

### 基本仕様

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

### PDF固有設定

該当なし

### Excel固有設定

該当なし

## 帳票レイアウト

### レイアウト概要

CodegenResult型はNo.1と同一構造。compiler-dom固有のトランスフォームが適用された状態でのコード生成結果。

```
┌─────────────────────────────────────┐
│         CodegenResult               │
├─────────────────────────────────────┤
│  code: string                       │
│  （DOM最適化されたrender関数コード）   │
├─────────────────────────────────────┤
│  preamble: string                   │
├─────────────────────────────────────┤
│  ast: RootNode                      │
├─────────────────────────────────────┤
│  map?: RawSourceMap                 │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | code | DOM向けrender関数コード（v-html, v-text, v-model等のDOMトランスフォーム適用済み） | baseCompile結果 | string |
| 2 | preamble | プリアンブルコード | baseCompile結果 | string |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | ast | DOMNodeTransforms適用済みRootNode | baseCompile結果 | RootNode | - |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | map | ソースマップ | baseCompile結果 | RawSourceMap / undefined |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| src | テンプレート文字列またはRootNode | Yes |
| options | CompilerOptions（DOM固有オプションを含む） | No（デフォルト値あり） |

### ソート順

該当なし

### 改ページ条件

該当なし

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

該当なし（インメモリ処理）

### 参照テーブル一覧

該当なし

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

該当なし

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| nodeTransforms | [ignoreSideEffectTags, ...DOMNodeTransforms, ...options.nodeTransforms] | - | ユーザーカスタムトランスフォームをマージ |
| directiveTransforms | extend({}, DOMDirectiveTransforms, options.directiveTransforms) | - | ユーザーカスタムディレクティブトランスフォームをマージ |
| transformHoist | __BROWSER__ ? null : stringifyStatic | - | 非ブラウザビルド時のみ静的ノード文字列化を有効化 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[compile関数呼び出し] --> B[parserOptionsとoptionsをマージ]
    B --> C[nodeTransforms構築]
    C --> D[DOMNodeTransforms追加]
    D --> E[directiveTransforms構築]
    E --> F[DOMDirectiveTransforms適用]
    F --> G[baseCompile呼び出し]
    G --> H[baseParse - テンプレートパース]
    H --> I[transform - AST変換]
    I --> J[generate - コード生成]
    J --> K[CodegenResult返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| HTMLネスティングエラー | DEVモードでHTML要素の不正なネスティング | validateHtmlNestingにより警告 | テンプレートのHTML構造を修正 |
| DOMエラー | DOM固有の不正なテンプレート構文 | DOMErrorMessagesに定義されたメッセージ | テンプレート構文を修正 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1コンポーネントにつき1回 |
| 目標出力時間 | ミリ秒オーダー |
| 同時出力数上限 | 制限なし（同期処理） |

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

v-htmlディレクティブはinnerHTMLを直接設定するため、XSS攻撃のリスクがある。ユーザー入力をv-htmlで表示する場合はサニタイズが必要。v-textやマスタッシュ構文（{{ }}）は自動的にエスケープされる。

## 備考

- DOMNodeTransformsには`transformStyle`（インラインスタイルの処理）が常に含まれ、DEVモードでは`transformTransition`と`validateHtmlNesting`が追加される。
- DOMDirectiveTransformsは`cloak`（noopDirectiveTransform）、`html`、`text`、`model`、`on`、`show`の6つのディレクティブトランスフォームを提供する。
- `ignoreSideEffectTags`はDOMNodeTransformsの前に配置され、`<script>`や`<style>`タグを無視する（compiler-ssrのvnode fallback分岐では使用されないため、DOMNodeTransformsには含まれない）。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | codegen.ts | `packages/compiler-core/src/codegen.ts` | CodegenResult型（108-113行目）- 出力型はcompiler-coreと共通 |

**読解のコツ**: compiler-domはcompiler-coreの型をそのまま使用するため、追加の型定義はない。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/compiler-dom/src/index.ts` | compile関数（41-64行目）がエントリーポイント |

**主要処理フロー**:
1. **45行目**: `baseCompile`を呼び出し（compiler-coreのbaseCompileに委譲）
2. **47行目**: `extend({}, parserOptions, options, {...})`でオプションをマージ
3. **48-55行目**: `nodeTransforms`にignoeSideEffectTags、DOMNodeTransforms、ユーザートランスフォームを結合
4. **56-60行目**: `directiveTransforms`にDOMDirectiveTransformsとユーザートランスフォームをマージ
5. **61行目**: `transformHoist`にstringifyStaticを設定（非ブラウザビルド時）

#### Step 3: DOMトランスフォームを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/compiler-dom/src/index.ts` | DOMNodeTransforms配列（27-30行目）とDOMDirectiveTransforms辞書（32-39行目） |
| 3-2 | transformStyle.ts | `packages/compiler-dom/src/transforms/transformStyle.ts` | インラインスタイルのAST変換 |
| 3-3 | vHtml.ts | `packages/compiler-dom/src/transforms/vHtml.ts` | v-htmlディレクティブの変換 |
| 3-4 | vModel.ts | `packages/compiler-dom/src/transforms/vModel.ts` | DOM用v-modelの変換（input/select/textarea対応） |
| 3-5 | vOn.ts | `packages/compiler-dom/src/transforms/vOn.ts` | DOM用v-onの変換（イベント修飾子対応） |

#### Step 4: baseCompileの内部処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | compile.ts | `packages/compiler-core/src/compile.ts` | baseCompile関数（67-122行目）- parse -> transform -> generate |

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

```
compile (compiler-dom/src/index.ts:41)
    |
    +-- baseCompile (compiler-core/src/compile.ts:67)
            |
            +-- baseParse (compiler-core/src/parser.ts)
            |
            +-- transform (compiler-core/src/transform.ts)
            |       +-- ignoreSideEffectTags
            |       +-- transformStyle (DOMNodeTransform)
            |       +-- transformTransition (DEVのみ)
            |       +-- validateHtmlNesting (DEVのみ)
            |       +-- transformVHtml (DOMDirectiveTransform)
            |       +-- transformVText (DOMDirectiveTransform)
            |       +-- transformModel (DOMDirectiveTransform)
            |       +-- transformOn (DOMDirectiveTransform)
            |       +-- transformShow (DOMDirectiveTransform)
            |
            +-- generate (compiler-core/src/codegen.ts:283)
                    +-- CodegenResult を返却
```

### データフロー図

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

テンプレート文字列       ──▶  baseParse                   ──▶  RootNode (AST)
  or RootNode                    |
                           transform                     ──▶  変換済みAST
                           (DOM固有トランスフォーム適用)
                                 |
                           generate                      ──▶  CodegenResult
                                                                { code, preamble, ast, map }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/compiler-dom/src/index.ts` | ソース | compile関数、DOMNodeTransforms、DOMDirectiveTransformsの定義 |
| parserOptions.ts | `packages/compiler-dom/src/parserOptions.ts` | ソース | DOM固有のパーサーオプション（isNativeTag、isVoidTag等） |
| transformStyle.ts | `packages/compiler-dom/src/transforms/transformStyle.ts` | ソース | インラインスタイルの変換 |
| vHtml.ts | `packages/compiler-dom/src/transforms/vHtml.ts` | ソース | v-htmlディレクティブ変換 |
| vText.ts | `packages/compiler-dom/src/transforms/vText.ts` | ソース | v-textディレクティブ変換 |
| vModel.ts | `packages/compiler-dom/src/transforms/vModel.ts` | ソース | v-model（DOM版）ディレクティブ変換 |
| vOn.ts | `packages/compiler-dom/src/transforms/vOn.ts` | ソース | v-on（DOM版）ディレクティブ変換 |
| vShow.ts | `packages/compiler-dom/src/transforms/vShow.ts` | ソース | v-showディレクティブ変換 |
| Transition.ts | `packages/compiler-dom/src/transforms/Transition.ts` | ソース | Transitionコンポーネント変換（DEVのみ） |
| stringifyStatic.ts | `packages/compiler-dom/src/transforms/stringifyStatic.ts` | ソース | 静的ノードの文字列化最適化 |
| ignoreSideEffectTags.ts | `packages/compiler-dom/src/transforms/ignoreSideEffectTags.ts` | ソース | script/styleタグの無視 |
| validateHtmlNesting.ts | `packages/compiler-dom/src/transforms/validateHtmlNesting.ts` | ソース | HTMLネスティング検証（DEVのみ） |
| errors.ts | `packages/compiler-dom/src/errors.ts` | ソース | DOMErrorCodes、DOMErrorMessages定義 |
| compile.ts | `packages/compiler-core/src/compile.ts` | ソース | baseCompile関数 |
| codegen.ts | `packages/compiler-core/src/codegen.ts` | ソース | generate関数、CodegenResult型 |
