# 機能設計書 67-AST出力（--debug-print-ast）

## 概要

本ドキュメントは、Prettierのコードフォーマッタにおける「AST出力」機能の設計を記述する。この機能は、パースされたソースコードのAST（Abstract Syntax Tree）をJSON形式で出力するデバッグ用の機能である。

### 本機能の処理概要

**業務上の目的・背景**：プラグイン開発者やPrettierのコントリビューターにとって、パース結果のAST構造を確認することは非常に重要である。--debug-print-astオプションは、任意のソースコードをパースした結果のAST構造をJSON形式で出力し、パーサーの動作確認やデバッグを可能にする。これにより、フォーマット結果が期待通りでない場合に、パース段階で問題が発生しているかどうかを切り分けることができる。

**機能の利用シーン**：
- プラグイン開発時のパーサー動作確認
- フォーマット結果の問題調査（パース段階の検証）
- Prettier本体の開発・デバッグ
- パーサー間の出力比較
- 教育目的でのAST構造の学習

**主要な処理内容**：
1. CLIから--debug-print-astオプションを受け取る
2. 指定されたファイルまたは標準入力をパースする
3. パース結果のASTをJSON.stringifyで文字列化
4. 結果を標準出力に出力

**関連システム・外部連携**：
- パーサーシステム: 各言語のパーサーを使用してAST生成
- CLI: オプション解析とファイル処理

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

## 関連画面

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

## 機能種別

デバッグ機能 / 出力処理

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ast | string | JSON形式のAST文字列 |

### 出力先

- 標準出力（stdout）

## 処理フロー

### 処理シーケンス

```
1. CLIでdebugPrintAstオプションを検出
   └─ cli-options.evaluate.jsで定義
2. format関数内で分岐処理
   └─ context.argv.debugPrintAstがtrueの場合
3. __debug.parse APIを呼び出し
   └─ ソースコードをパースしてASTを取得
4. ASTをJSON.stringifyで文字列化
   └─ 整形なしのJSON出力
5. 結果をformattedとして返却
   └─ 標準出力に出力される
```

### フローチャート

```mermaid
flowchart TD
    A[CLI実行] --> B{debugPrintAst?}
    B -->|No| C[通常フォーマット処理]
    B -->|Yes| D[__debug.parse呼び出し]
    D --> E[AST取得]
    E --> F[JSON.stringify ast]
    F --> G[formatted として返却]
    G --> H[標準出力に出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-67-01 | JSON形式出力 | ASTはJSON.stringify()で文字列化 | 常時 |
| BR-67-02 | 整形なし | インデントなしのコンパクトなJSON | 整形はjqなど外部ツールで |
| BR-67-03 | パーサー推論 | --parserが未指定の場合はファイル拡張子から推論 | ファイル指定時 |

### 計算ロジック

特になし

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

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

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

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

該当なし

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし

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

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

## パフォーマンス要件

- パース処理は通常のフォーマットと同等の時間
- 大きなファイルの場合はJSON.stringifyに時間がかかる可能性

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

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

## 備考

- このオプションはデバッグ目的であり、通常の使用では必要ない
- --debug-print-docと組み合わせることで、パース→Doc生成の両方を確認可能

---

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

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

### 推奨読解順序

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

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

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

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

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

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

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

**主要処理フロー**:
- **119-124行目**: debugPrintAstの処理
- **120行目**: __debug.parseの呼び出し
- **121-123行目**: ASTをJSON文字列として返却

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

デバッグparse APIの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.js | `src/main/core.js` | parse関数の実装 |
| 3-2 | index.js | `src/index.js` | __debug.parseのエクスポート |

**主要処理フロー（core.js）**:
- **369-384行目**: parse関数の実装
- **370-373行目**: オプションの正規化
- **374行目**: parseTextの呼び出し
- **375-382行目**: devOptionsの処理（preprocessForPrint、massage）

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

```
CLI (format.js)
    │
    └─ format (format.js)
           │
           └─ context.argv.debugPrintAst判定
                  │
                  └─ prettier.__debug.parse (index.js)
                         │
                         └─ core.parse (core.js)
                                │
                                ├─ normalizeInputAndOptions
                                │
                                ├─ normalizeFormatOptions
                                │
                                └─ parseText (parse.js)
                                       │
                                       └─ 言語パーサー
```

### データフロー図

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

file/stdin ───────────▶ format.js
                            │
                            ▼
                       debugPrintAst判定
                            │
                            ▼
                       __debug.parse
                            │
                            ▼
options ─────────────▶ normalizeFormatOptions
                            │
                            ▼
                       parseText
                            │
                            ▼
                       {ast, text}
                            │
                            ▼
                       JSON.stringify(ast) ─────────────▶ stdout
```

### 関連ファイル一覧

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