# 機能設計書 68-Doc出力（--debug-print-doc）

## 概要

本ドキュメントは、Prettierのコードフォーマッタにおける「Doc出力」機能の設計を記述する。この機能は、フォーマット処理で生成されるPrettierの中間表現（Doc）をデバッグ出力するための機能である。

### 本機能の処理概要

**業務上の目的・背景**：Prettierは、AST（抽象構文木）からDoc（中間表現）を生成し、Docから最終的な文字列を生成するという2段階のプロセスでフォーマットを行う。--debug-print-docオプションは、この中間表現であるDocを可読形式で出力し、プラグイン開発者がフォーマット結果の問題を調査する際に、Doc生成段階で問題が発生しているかどうかを切り分けることを可能にする。

**機能の利用シーン**：
- プラグイン開発時のDoc生成ロジックの確認
- フォーマット結果の問題調査（Doc生成段階の検証）
- Prettier本体の開発・デバッグ
- Doc構造の学習・理解
- line、group、indent等のDoc命令の動作確認

**主要な処理内容**：
1. CLIから--debug-print-docオプションを受け取る
2. 指定されたファイルまたは標準入力をパースし、ASTを生成
3. ASTからDocを生成（printToDoc）
4. Docを可読形式に変換（formatDoc）
5. 結果を標準出力に出力

**関連システム・外部連携**：
- パーサーシステム: AST生成
- プリンターシステム: Doc生成
- Document Builder API: Doc構造

**権限による制御**：特になし（CLI機能）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | Usage - CLI | 補助機能 | CLIでのデバッグDoc出力を説明 |

## 機能種別

デバッグ機能 / 出力処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --debug-print-doc | boolean | Yes | Doc出力を有効化 | - |
| file | string | Yes | フォーマット対象ファイル（または--stdin-filepath） | 存在するファイルパス |
| --parser | string | No | 使用するパーサー | 有効なパーサー名 |

### 入力データソース

- CLIコマンドライン引数
- ファイルまたは標準入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| doc | string | 整形されたDoc文字列（改行付き） |

### 出力先

- 標準出力（stdout）

## 処理フロー

### 処理シーケンス

```
1. CLIでdebugPrintDocオプションを検出
   └─ cli-options.evaluate.jsで定義
2. format関数内で分岐処理
   └─ context.argv.debugPrintDocがtrueの場合
3. __debug.printToDoc APIを呼び出し
   └─ ソースコードをパースしてDocを生成
4. __debug.formatDoc APIを呼び出し
   └─ Docを可読形式に変換
5. 結果に改行を追加してformattedとして返却
   └─ 標準出力に出力される
```

### フローチャート

```mermaid
flowchart TD
    A[CLI実行] --> B{debugPrintDoc?}
    B -->|No| C[通常フォーマット処理]
    B -->|Yes| D[__debug.printToDoc呼び出し]
    D --> E[Doc取得]
    E --> F[__debug.formatDoc呼び出し]
    F --> G[可読形式のDoc文字列]
    G --> H[改行を追加]
    H --> I[formatted として返却]
    I --> J[標準出力に出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-68-01 | 可読形式出力 | DocはformatDocで可読形式に変換 | 常時 |
| BR-68-02 | 末尾改行 | 出力の末尾に改行を追加 | 常時 |
| BR-68-03 | JS式として出力 | Docは__js_expressionパーサーで整形 | formatDoc内部 |

### 計算ロジック

特になし

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

### 操作別データベース影響一覧

本機能はデータベース操作を伴わない。

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パースエラー | ソースコードの構文エラー | エラーメッセージを出力 |
| - | ファイルエラー | 指定ファイルが存在しない | エラーメッセージを出力 |
| - | パーサーエラー | 不明なパーサー指定 | UndefinedParserError |

### リトライ仕様

該当なし

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

該当なし（データベース操作なし）

## パフォーマンス要件

- Doc生成は通常のフォーマットと同等の時間
- formatDocの処理はDoc構造のサイズに依存

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

- 特別なセキュリティ要件なし
- 出力にはソースコードの構造が含まれる

## 備考

- このオプションはデバッグ目的であり、通常の使用では必要ない
- --debug-print-astと組み合わせることで、パース→Doc生成の両方を確認可能
- formatDocは内部的に__js_expressionパーサーを使用してDoc文字列を整形する

---

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

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

### 推奨読解順序

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

CLIオプションの定義を確認する。

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

**読解のコツ**: オプションはtype: "boolean"として定義され、descriptionがないため--helpには表示されない内部オプション。

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

CLIのフォーマット処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | format.js | `src/cli/format.js` | format関数内のdebugPrintDoc分岐 |

**主要処理フロー**:
- **103-106行目**: debugPrintDocの処理
- **104行目**: __debug.printToDocの呼び出し
- **105行目**: __debug.formatDocの呼び出しと改行追加

#### Step 3: printToDoc APIを理解する

Doc生成APIの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.js | `src/main/core.js` | printToDoc関数の実装 |

**主要処理フロー**:
- **403-415行目**: printToDoc関数の実装
- **404行目**: normalizeFormatOptionsの呼び出し
- **405行目**: parseTextでASTを取得
- **414行目**: printAstToDocでDocを生成

#### Step 4: formatDoc APIを理解する

Doc整形APIの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | core.js | `src/main/core.js` | formatDoc関数の実装 |

**主要処理フロー**:
- **393-401行目**: formatDoc関数の実装
- **394行目**: printDocToDebugでDoc文字列に変換
- **395-399行目**: __js_expressionパーサーで整形

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

```
CLI (format.js)
    │
    └─ format (format.js)
           │
           └─ context.argv.debugPrintDoc判定
                  │
                  ├─ prettier.__debug.printToDoc (index.js)
                  │      │
                  │      └─ core.printToDoc (core.js)
                  │             │
                  │             ├─ normalizeFormatOptions
                  │             │
                  │             ├─ parseText
                  │             │
                  │             └─ printAstToDoc (ast-to-doc.js)
                  │
                  └─ prettier.__debug.formatDoc (index.js)
                         │
                         └─ core.formatDoc (core.js)
                                │
                                ├─ printDocToDebug (document/index.js)
                                │
                                └─ formatWithCursor (__js_expression)
```

### データフロー図

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

file/stdin ───────────▶ format.js
                            │
                            ▼
                       debugPrintDoc判定
                            │
                            ▼
                       __debug.printToDoc
                            │
                            ▼
options ─────────────▶ normalizeFormatOptions
                            │
                            ▼
                       parseText → AST
                            │
                            ▼
                       printAstToDoc → Doc
                            │
                            ▼
                       __debug.formatDoc
                            │
                            ▼
                       printDocToDebug → Doc文字列
                            │
                            ▼
                       formatWithCursor → 整形されたDoc
                            │
                            ▼
                       + "\n" ──────────────────────────▶ stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ソース | CLIオプション定義 |
| format.js | `src/cli/format.js` | ソース | CLI フォーマット処理、debugPrintDoc分岐 |
| core.js | `src/main/core.js` | ソース | printToDoc、formatDoc関数の実装 |
| index.js | `src/index.js` | ソース | __debug APIのエクスポート |
| ast-to-doc.js | `src/main/ast-to-doc.js` | ソース | printAstToDoc関数 |
| index.js | `src/document/index.js` | ソース | printDocToDebug関数 |
