# 機能設計書 58-埋め込み言語フォーマット（embeddedLanguageFormatting）

## 概要

本ドキュメントは、Prettierの`embeddedLanguageFormatting`オプションに関する機能設計書である。このオプションは、ファイル内に埋め込まれた別言語のコード（例：HTMLテンプレート内のJavaScript、Markdown内のコードブロック）をフォーマットするかどうかを制御する。

### 本機能の処理概要

**業務上の目的・背景**：多くのファイル形式では、他の言語のコードが埋め込まれている。Markdown内のコードブロック、HTMLの`<script>`タグ内のJavaScript、テンプレートリテラル内のSQLなどが例として挙げられる。これらの埋め込みコードもフォーマットすることで、ファイル全体の一貫性を保てる。ただし、フォーマットが望ましくない場合もあるため、このオプションで制御できる。

**機能の利用シーン**：埋め込みコードを含むファイルのフォーマット時に使用される。特に、Markdownドキュメント、HTMLテンプレート、テンプレートリテラルを多用するコードで重要である。

**主要な処理内容**：
1. オプション値（auto/off）の読み込み
2. autoの場合、埋め込み言語を自動検出
3. 検出された言語のパーサーを呼び出し
4. 埋め込みコードをフォーマットして元の位置に挿入

**関連システム・外部連携**：マルチパーサーシステム、各言語のプリンターと連携して動作する。

**権限による制御**：権限による制御は存在しない。設定ファイルまたはCLIオプションで指定する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Playground | 補助機能 | サイドバーから埋め込み言語フォーマットオプションを設定 |
| 19 | Configuration - Options | 主機能 | embeddedLanguageFormattingオプションの詳細説明 |

## 機能種別

設定オプション / フォーマット制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| embeddedLanguageFormatting | choice | No | 埋め込み言語のフォーマット制御 | "auto", "off"のいずれか |

### 入力データソース

- 設定ファイル（.prettierrc、prettier.config.js等）
- CLIオプション（--embedded-language-formatting）
- プログラマティックAPI呼び出し時のオプションオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| formattedCode | string | 埋め込み言語設定が適用されたフォーマット済みコード |

### 出力先

フォーマット結果は呼び出し元に返却される（標準出力、ファイル、API戻り値）。

## 処理フロー

### 処理シーケンス

```
1. オプション解析
   └─ embeddedLanguageFormattingオプションの値を取得（デフォルト: "auto"）
2. オプション判定
   └─ "auto"でない場合、埋め込み言語処理をスキップ
3. 埋め込み言語検出
   └─ printer.embed関数で埋め込み言語を検出
4. パーサー選択
   └─ 検出された言語に対応するパーサーを選択
5. 埋め込みコードフォーマット
   └─ textToDoc関数で埋め込みコードをフォーマット
6. 結果マージ
   └─ フォーマット済みの埋め込みコードを元のDocに統合
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{embeddedLanguageFormatting?}
    B -->|off| C[埋め込み言語処理をスキップ]
    B -->|auto| D[埋め込み言語を検出]
    D --> E{検出成功?}
    E -->|No| F[そのまま出力]
    E -->|Yes| G[対応パーサーを選択]
    G --> H[textToDocでフォーマット]
    H --> I[結果をDocに統合]
    C --> J[最終出力]
    F --> J
    I --> J
    J --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-58-1 | デフォルト動作 | 自動的に埋め込み言語を検出してフォーマット | embeddedLanguageFormatting = "auto"（デフォルト） |
| BR-58-2 | 無効化 | 埋め込み言語をフォーマットしない | embeddedLanguageFormatting = "off" |
| BR-58-3 | printer.embed | 各プリンターのembed関数で検出・処理 | auto時 |
| BR-58-4 | エラーハンドリング | フォーマット失敗時はそのまま出力 | 常時 |
| BR-58-5 | 対応言語 | テンプレートリテラル、Markdownコードブロック等 | printer実装依存 |

### 計算ロジック

特別な計算ロジックは存在しない。

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

データベース操作は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パースエラー | 埋め込みコードのパースに失敗 | エラーをキャッチしてそのまま出力 |
| - | 値エラー | 未定義の値が指定された場合 | Prettierのオプション検証でエラーが発生 |

### リトライ仕様

リトライは不要。エラー発生時はそのまま出力される。

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

トランザクション管理は不要。

## パフォーマンス要件

埋め込み言語ごとにパーサーを呼び出すため、多くの埋め込みがある場合はパフォーマンスに影響する可能性がある。

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

セキュリティに関する特別な考慮事項は存在しない。

## 備考

- 各プリンターのembed関数が埋め込み言語の検出と処理を担当する。
- フォーマット失敗時はエラーをスローせず、元のコードをそのまま出力する。
- MDX内のJSX、テンプレートリテラル内のGraphQL等、様々な組み合わせをサポート。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | core-options.evaluate.js | `src/main/core-options.evaluate.js` | embeddedLanguageFormattingオプションの定義 |

**読解のコツ**: このファイルでは、embeddedLanguageFormattingがchoice型で2つの選択肢（auto, off）を持つことを確認する。

#### Step 2: マルチパーサー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | multiparser.js | `src/main/multiparser.js` | printEmbeddedLanguages関数 |

**主要処理フロー**:
1. **14行目**: embeddedLanguageFormatting !== "auto"の場合、処理をスキップ
2. **18-29行目**: printer.embedの存在チェックと検証
3. **40-47行目**: embed関数の結果を処理
4. **58-60行目**: textToDocForEmbed関数で埋め込みコードをフォーマット
5. **108-132行目**: textToDoc関数の実装

#### Step 3: エラーハンドリングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | multiparser.js | `src/main/multiparser.js` | try-catchでのエラー処理 |

**主要処理フロー**:
- **48-53行目**: try-catchでエラーをキャッチし、PRETTIER_DEBUG以外では無視

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

```
printAstToDoc (ast-to-doc.js)
    │
    └─ printEmbeddedLanguages (multiparser.js:7)
           │
           ├─ options.embeddedLanguageFormatting チェック (14行目)
           │      └─ "auto"でない場合は早期リターン
           │
           ├─ printer.embed 呼び出し (80行目)
           │      └─ 各言語プリンターのembed関数
           │
           └─ textToDoc (108行目)
                  ├─ normalizeFormatOptions
                  ├─ parse
                  └─ printAstToDoc (再帰)
```

### データフロー図

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

オプション設定 ───▶ printEmbeddedLanguages ───▶ 埋め込みDoc
(embeddedLanguageFormatting)  (multiparser.js)
        │
        ▼
        "auto" ───▶ printer.embed呼び出し ───▶ 検出結果
        │
        ▼
        検出言語 ───▶ textToDoc ───▶ フォーマット済みDoc
                      (再帰呼び出し)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| core-options.evaluate.js | `src/main/core-options.evaluate.js` | ソース | オプション定義（204-221行目） |
| multiparser.js | `src/main/multiparser.js` | ソース | 埋め込み言語処理 |
| ast-to-doc.js | `src/main/ast-to-doc.js` | ソース | printEmbeddedLanguages呼び出し |
| index.d.ts | `src/index.d.ts` | 型定義 | TypeScript型定義（432行目） |
| mdast.js | `src/language-markdown/print/mdast.js` | ソース | Markdownでの参照（358行目） |
