# 機能設計書 69-ベンチマーク（--debug-benchmark）

## 概要

本ドキュメントは、Prettierのコードフォーマッタにおける「ベンチマーク」機能の設計を記述する。この機能は、フォーマット処理のパフォーマンスを測定するためのデバッグ用機能である。

### 本機能の処理概要

**業務上の目的・背景**：Prettierのパフォーマンス最適化やリグレッションテストにおいて、フォーマット処理の実行時間を計測することは重要である。--debug-benchmarkオプションは、tinybenchライブラリを使用して正確なベンチマークを実行し、フォーマット処理の速度を測定する。これにより、コード変更によるパフォーマンスへの影響を定量的に評価できる。

**機能の利用シーン**：
- Prettier本体のパフォーマンス最適化
- プラグインのパフォーマンス測定
- リグレッションテスト（パフォーマンス低下の検出）
- 異なるパーサー間のパフォーマンス比較
- CI/CDパイプラインでのパフォーマンス監視

**主要な処理内容**：
1. CLIから--debug-benchmarkオプションを受け取る
2. tinybenchライブラリをインポート（動的インポート）
3. ベンチマークインスタンスを作成
4. formatWithCursorを繰り返し実行してベンチマーク測定
5. 結果（ops/sec、平均時間等）をJSON形式でログ出力

**関連システム・外部連携**：
- 外部ライブラリ: tinybench（ベンチマーク測定）
- CLI: オプション解析とファイル処理

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | Usage - CLI | 補助機能 | CLIでのベンチマーク機能を説明 |

## 機能種別

デバッグ機能 / パフォーマンス計測

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --debug-benchmark | boolean | Yes | ベンチマークを有効化 | - |
| file | string | Yes | フォーマット対象ファイル | 存在するファイルパス |
| --parser | string | No | 使用するパーサー | 有効なパーサー名 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Task name | string | ベンチマーク名（"Format"） |
| ops/sec | number | 1秒あたりの操作数 |
| Average Time (ns) | number | 平均実行時間（ナノ秒） |
| Margin | number | 誤差マージン |
| Samples | number | サンプル数 |

### 出力先

- 標準エラー出力（stderr）にデバッグログとして出力

## 処理フロー

### 処理シーケンス

```
1. CLIでdebugBenchmarkオプションを検出
   └─ cli-options.evaluate.jsで定義
2. performanceTestFlagとしてコンテキストに設定
3. format関数内でperformanceTestFlagを確認
4. tinybenchライブラリを動的インポート
   └─ インストールされていない場合はエラーメッセージを出力して終了
5. Benchインスタンスを作成
6. "Format"タスクを追加（formatWithCursor呼び出し）
7. ベンチマークを実行
8. 結果をJSON形式でデバッグログに出力
9. 画面出力をスキップ（パフォーマンステスト中は出力しない）
```

### フローチャート

```mermaid
flowchart TD
    A[CLI実行] --> B{debugBenchmark?}
    B -->|No| C[通常フォーマット処理]
    B -->|Yes| D[tinybench動的インポート]
    D --> E{インポート成功?}
    E -->|No| F[エラーメッセージ出力]
    F --> G[exit 2]
    E -->|Yes| H[Benchインスタンス作成]
    H --> I[bench.add 'Format' タスク]
    I --> J[bench.run 実行]
    J --> K[bench.table 結果取得]
    K --> L[JSON形式でログ出力]
    L --> M[画面出力スキップ]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-69-01 | tinybench必須 | tinybenchパッケージが必要 | ベンチマーク実行時 |
| BR-69-02 | 結果出力形式 | JSON形式でデバッグログに出力 | ベンチマーク完了後 |
| BR-69-03 | 画面出力スキップ | ベンチマーク中はフォーマット結果を出力しない | パフォーマンス影響を避けるため |
| BR-69-04 | formatWithCursor使用 | ベンチマークはformatWithCursorで測定 | カーソル位置追跡を含む完全な処理 |

### 計算ロジック

tinybenchが提供するメトリクス:
- ops/sec: 1秒あたりの操作回数
- Average Time: 平均実行時間
- Margin: 統計的誤差マージン
- Samples: 測定サンプル数

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

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

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| exit 2 | 依存エラー | tinybenchがインストールされていない | パッケージをインストール |
| - | パースエラー | ソースコードの構文エラー | エラーメッセージを出力 |

### リトライ仕様

該当なし

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

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

## パフォーマンス要件

- ベンチマーク自体のオーバーヘッドは最小限
- 複数回の実行による統計的に有意な結果を提供

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

- 特別なセキュリティ要件なし
- 外部パッケージ（tinybench）への依存

## 備考

- このオプションはデバッグ目的であり、通常の使用では必要ない
- tinybenchパッケージは開発依存関係として管理されることが推奨される
- --debug-repeatオプションと組み合わせることも可能

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: オプションはtype: "boolean"として定義。コメントに"requires 'benchmark' module to be installed"と記載（現在はtinybench）。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | format.js | `src/cli/format.js` | format関数内のベンチマーク処理 |

**主要処理フロー**:
- **161-162行目**: performanceTestFlag.debugBenchmarkの判定
- **163-171行目**: tinybenchのインポートとエラーハンドリング
- **172-183行目**: ベンチマーク実行と結果出力

#### Step 3: performanceTestFlagの設定を理解する

コンテキストへのフラグ設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | context.js | `src/cli/context.js` | performanceTestFlagの設定（推定） |

**主要処理フロー（format.js）**:
- **175-176行目**: Benchインスタンスの作成
- **176行目**: `bench.add("Format", () => prettier.formatWithCursor(input, opt))`
- **177行目**: `await bench.run()` でベンチマーク実行
- **179-183行目**: 結果をJSON形式でログ出力

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

```
CLI (format.js)
    │
    └─ format (format.js)
           │
           └─ performanceTestFlag.debugBenchmark判定
                  │
                  ├─ import("tinybench") [動的インポート]
                  │      │
                  │      └─ Bench クラス取得
                  │
                  ├─ bench = new Bench()
                  │
                  ├─ bench.add("Format", formatWithCursor)
                  │
                  ├─ await bench.run()
                  │
                  └─ bench.table() → JSON出力
```

### データフロー図

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

file/stdin ───────────▶ format.js
                            │
                            ▼
                       debugBenchmark判定
                            │
                            ▼
                       tinybench動的インポート
                            │
                            ▼
                       Benchインスタンス作成
                            │
options ─────────────▶ bench.add("Format",
                            │   formatWithCursor)
                            │
                            ▼
                       bench.run()
                            │
                            ▼
                       bench.table()
                            │
                            ▼
                       JSON.stringify(result) ──────────▶ stderr (debug log)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ソース | CLIオプション定義 |
| format.js | `src/cli/format.js` | ソース | ベンチマーク実行ロジック |
| index.js | `src/index.js` | ソース | formatWithCursorの提供 |
| tinybench | node_modules | 外部ライブラリ | ベンチマーク測定 |
