# 機能設計書 9-@babel/template

## 概要

本ドキュメントは、BabelのASTテンプレートエンジンである`@babel/template`パッケージの設計仕様を記述する。このパッケージは、文字列テンプレートからASTノードを生成する機能を提供し、コード生成を簡潔に記述できるようにする。

### 本機能の処理概要

**業務上の目的・背景**：Babelプラグインでコードを生成する際、@babel/typesのビルダー関数を使用して手動でASTを構築すると冗長になりがちである。@babel/templateは、人間が読みやすいコード文字列からASTを生成し、プレースホルダーを使った動的な値の挿入を可能にすることで、プラグイン開発の生産性を大幅に向上させる。

**機能の利用シーン**：Babelプラグインでコード変換を行う場合、ランタイムヘルパーコードを生成する場合、動的にコードを構築する場合に利用される。

**主要な処理内容**：
1. テンプレート文字列の解析
2. プレースホルダーの識別と置換
3. ASTノードの生成
4. タグ付きテンプレートリテラルサポート
5. 複数の出力形式（smart, statement, statements, expression, program）

**関連システム・外部連携**：@babel/parser（テンプレート解析）、@babel/types（AST操作）と連携する。

**権限による制御**：特になし。純粋なメモリ内処理のみ。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | プログラマティックなAPIとして動作 |

## 機能種別

テンプレートエンジン

## 入力仕様

### 入力パラメータ

#### template(code, opts?)
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| code | string | Yes | テンプレートコード |
| opts | Options | No | テンプレートオプション |

#### template``（タグ付きテンプレート）
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| strings | TemplateStringsArray | Yes | テンプレート文字列部分 |
| ...args | any[] | No | 埋め込み値 |

### Options

| パラメータ名 | 型 | 必須 | 説明 | デフォルト |
|-------------|-----|-----|------|---------|
| placeholderWhitelist | Set<string> | No | 許可するプレースホルダー名 | - |
| placeholderPattern | RegExp \| false | No | プレースホルダーパターン | /^[_$A-Z0-9]+$/ |
| preserveComments | boolean | No | コメントを保持 | false |
| syntacticPlaceholders | boolean | No | %%name%%形式のプレースホルダー | false |

### テンプレートビルダー種別

| ビルダー | 説明 | 戻り値 |
|---------|------|-------|
| template.smart | 自動判定（文/式/プログラム） | 適切なノード |
| template.statement | 単一文として解析 | Statement |
| template.statements | 文の配列として解析 | Statement[] |
| template.expression | 式として解析 | Expression |
| template.program | プログラムとして解析 | Program |

### 入力データソース

- プラグインからの直接呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 返却関数 | Function | 置換関数 |
| (置換後) | t.Node | 生成されたASTノード |

### 出力先

- 呼び出し元への直接返却

## 処理フロー

### 処理シーケンス

```
1. templateビルダーの呼び出し
   └─ テンプレート文字列とオプションを受け取る
2. テンプレートの解析
   └─ プレースホルダーの識別
   └─ @babel/parserでAST生成
3. 置換関数の返却
   └─ キャッシュの確認/保存
4. 置換関数の実行
   └─ replacementsオブジェクトを受け取る
   └─ プレースホルダーをASTノードで置換
5. 結果ASTの返却
```

### フローチャート

```mermaid
flowchart TD
    A[template呼び出し] --> B{入力タイプ?}
    B -->|string| C[stringTemplate]
    B -->|TemplateStringsArray| D[literalTemplate]
    B -->|object| E[オプションマージ]
    C --> F[置換関数を返却]
    D --> G{キャッシュあり?}
    G -->|Yes| H[キャッシュから取得]
    G -->|No| I[literalTemplate生成]
    I --> J[キャッシュに保存]
    H --> F
    J --> F
    E --> K[新ビルダー生成]
    F --> L[置換関数実行]
    L --> M[プレースホルダー置換]
    M --> N[AST返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | プレースホルダーパターン | デフォルトで大文字スネークケース（_$A-Z0-9） | placeholderPattern未指定時 |
| BR-02 | smartモード | 単一式→Expression、単一文→Statement、複数→Statements | template.smart使用時 |
| BR-03 | astモード | プレースホルダーなしで即時AST生成 | template.ast使用時 |
| BR-04 | キャッシュ | タグ付きテンプレートはWeakMapでキャッシュ | 常時 |
| BR-05 | syntacticPlaceholders | %%NAME%%形式でプレースホルダーを明示 | syntacticPlaceholders: true |

### 計算ロジック

特になし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 構文エラー | 無効なテンプレート構文 | パースエラーメッセージ表示 |
| - | 置換エラー | 未定義プレースホルダーの参照 | エラーメッセージ表示 |
| - | パラメータエラー | 不正な引数の数 | エラーメッセージ表示 |

### リトライ仕様

リトライ機能なし

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

該当なし

## パフォーマンス要件

- タグ付きテンプレートはWeakMapでキャッシュされ、再利用時は高速
- 遅延パース: テンプレートは置換関数実行時に初めてパースされる

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

- テンプレートからASTを生成するのみで、コード実行は発生しない
- 信頼できないソースからのテンプレート使用は避けること

## 備考

- extendedTraceでエラースタックトレースを拡張し、デバッグを容易にする
- template.ast は中間関数を省略して直接ASTを返す

---

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

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

### 推奨読解順序

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

処理の起点となるファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-template/src/index.ts` | 公開APIの構造（1-31行目） |

**主要処理フロー**:
1. **4-8行目**: 各フォーマッターでビルダーを生成
2. **18-25行目**: デフォルトエクスポート（smart + 各ビルダーを統合）
3. **27-30行目**: 型定義のエクスポート

#### Step 2: ビルダー生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | builder.ts | `packages/babel-template/src/builder.ts` | createTemplateBuilder関数（42-99行目） |

**主要処理フロー**:
- **46-47行目**: キャッシュ用WeakMap
- **51-72行目**: テンプレートビルダー関数の実装
- **74-97行目**: astメソッドの実装

#### Step 3: フォーマッターを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | formatters.ts | `packages/babel-template/src/formatters.ts` | smart, statement, expression等の定義 |

#### Step 4: テンプレート処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | string.ts | `packages/babel-template/src/string.ts` | 文字列テンプレートの処理 |
| 4-2 | literal.ts | `packages/babel-template/src/literal.ts` | タグ付きテンプレートの処理 |

#### Step 5: オプション処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | options.ts | `packages/babel-template/src/options.ts` | merge, validate関数 |

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

```
@babel/template (index.ts)
    │
    ├─ smart = createTemplateBuilder(formatters.smart)
    ├─ statement = createTemplateBuilder(formatters.statement)
    ├─ statements = createTemplateBuilder(formatters.statements)
    ├─ expression = createTemplateBuilder(formatters.expression)
    └─ program = createTemplateBuilder(formatters.program)
           │
           └─ createTemplateBuilder (builder.ts)
                  │
                  ├─ (string) → stringTemplate (string.ts)
                  │      └─ @babel/parser.parse
                  │
                  ├─ (TemplateStringsArray) → literalTemplate (literal.ts)
                  │      └─ キャッシュ確認/保存
                  │
                  └─ (object) → 新ビルダー生成
```

### データフロー図

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

テンプレート文字列 ───────▶ stringTemplate ───────▶ 置換関数
"const X = VALUE"           (string.ts)

タグ付きテンプレート ───────▶ literalTemplate ───────▶ 置換関数
`const ${name} = ${val}`     (literal.ts)

置換オブジェクト ───────▶ 置換関数実行 ───────▶ ASTノード
{ VALUE: t.numericLiteral(1) }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-template/src/index.ts` | ソース | 公開APIのエントリーポイント |
| builder.ts | `packages/babel-template/src/builder.ts` | ソース | TemplateBuilder生成 |
| formatters.ts | `packages/babel-template/src/formatters.ts` | ソース | 出力形式定義 |
| string.ts | `packages/babel-template/src/string.ts` | ソース | 文字列テンプレート処理 |
| literal.ts | `packages/babel-template/src/literal.ts` | ソース | タグ付きテンプレート処理 |
| options.ts | `packages/babel-template/src/options.ts` | ソース | オプション処理 |
| parse.ts | `packages/babel-template/src/parse.ts` | ソース | テンプレートパース |
| populate.ts | `packages/babel-template/src/populate.ts` | ソース | プレースホルダー置換 |
