# 通知設計書 24---debug-benchmark measurements

## 概要

`--debug-benchmark`オプション使用時にベンチマーク測定結果をデバッグ出力する通知の設計書です。

### 本通知の処理概要

本通知は、Prettierの`--debug-benchmark`オプションを使用した際に、formatWithCursor関数のパフォーマンス測定結果を出力するものです。tinybenchモジュールを使用してベンチマーク測定を行い、その結果をJSON形式でデバッグログとして出力します。

**業務上の目的・背景**：Prettierのパフォーマンス最適化や回帰テストを行う際、フォーマット処理の実行速度を正確に測定することが重要です。この通知は、開発者やメンテナーがPrettierの性能を定量的に評価できるようにすることを目的としています。tinybenchを使用することで、正確で再現性のあるベンチマーク結果を取得できます。

**通知の送信タイミング**：`--debug-benchmark`オプションが指定された状態でファイルフォーマットを実行した際、format関数内でベンチマーク測定が完了した後に出力されます。具体的には、`format.js`のformat関数内でtinybenchの実行が完了した後に出力されます。

**通知の受信者**：CLIを実行している開発者（標準エラー出力経由）。

**通知内容の概要**：複数のデバッグメッセージが出力されます：
1. tinybenchパッケージが必要である旨のメッセージ（パッケージが見つからない場合）
2. ベンチマーク開始メッセージ
3. ベンチマーク測定結果（JSON形式）

**期待されるアクション**：開発者は出力された測定結果を確認し、パフォーマンスの評価や比較分析を行います。必要に応じて、コードの最適化や設定の調整を行います。

## 通知種別

CLIデバッグ出力（stderr）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 低（デバッグ情報） |
| リトライ | 無 |

### 送信先決定ロジック

`--debug-benchmark`オプションが指定されている場合、logLevelが自動的にdebugに設定され、`logger.debug`メソッドで出力されます。

## 通知テンプレート

### CLI出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr |
| プレフィックス | `[debug]`（青色） |
| 形式 | テキスト（JSON含む） |

### 本文テンプレート

#### ベンチマーク開始メッセージ
```
[debug] '--debug-benchmark' option found, measuring formatWithCursor with 'tinybench' module.
```

#### ベンチマーク結果メッセージ
```
[debug] '--debug-benchmark' measurements for formatWithCursor: {
  "Task Name": "Format",
  "ops/sec": "xxx.xx",
  "Average Time (ns)": xxxxx,
  ...
}
```

#### パッケージ不足エラーメッセージ
```
[debug] '--debug-benchmark' requires the 'tinybench' package to be installed.
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| result | ベンチマーク結果オブジェクト | bench.table()[0] | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | format関数実行時 | `context.performanceTestFlag?.debugBenchmark` がtrue | ベンチマーク測定後 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `--debug-benchmark`が未指定 | オプションが指定されていない場合は測定自体が行われない |
| tinybenchパッケージ未インストール | エラーメッセージ出力後、exitCode=2で終了 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[CLI実行開始] --> B{--debug-benchmark指定?}
    B -->|No| C[通常フォーマット処理]
    B -->|Yes| D[logLevelをdebugに設定]
    D --> E[format関数呼び出し]
    E --> F{performanceTestFlag?.debugBenchmark?}
    F -->|Yes| G[tinybenchインポート試行]
    G --> H{インポート成功?}
    H -->|No| I[エラーメッセージ出力]
    I --> J[exit 2]
    H -->|Yes| K[ベンチマーク開始メッセージ出力]
    K --> L[Benchインスタンス作成]
    L --> M[formatWithCursorタスク追加]
    M --> N[bench.run実行]
    N --> O[結果取得]
    O --> P[結果JSON出力]
    P --> Q[処理完了]
    F -->|No| C
```

## データベース参照・更新仕様

### 参照テーブル一覧

なし

### 更新テーブル一覧

なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| パッケージ未インストール | tinybenchがnode_modulesに存在しない | エラーメッセージを出力し、exit(2)で終了 |

### リトライ仕様

なし

## 配信設定

### レート制限

なし（CLI実行ごとに1回）

### 配信時間帯

制限なし

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

- ベンチマーク結果にはパフォーマンス情報のみが含まれ、機密情報は含まれない
- tinybenchパッケージの動的インポートを使用

## 備考

- tinybenchパッケージは開発依存関係として別途インストールが必要
- ベンチマーク測定中は実際のフォーマット処理が複数回実行される
- `--debug-benchmark`使用時は`performanceTestFlag`が設定され、logLevelがdebugに変更される
- 実際の出力はスキップされる（skipped print code to screen）

---

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

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

### 推奨読解順序

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

まず、performanceTestFlagオブジェクトの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | context.js | `src/cli/context.js` | performanceTestFlagゲッターの実装を確認 |
| 1-2 | cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | debugBenchmarkオプションの定義を確認 |

**読解のコツ**: context.jsの58-85行目でperformanceTestFlagの実装を確認。debugBenchmarkがtrueの場合の戻り値を理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/cli/index.js` | performanceTestFlag時のlogger設定変更を確認 |

**主要処理フロー**:
1. **28-30行目**: performanceTestFlag有効時のloggerをdebugに変更

#### Step 3: ベンチマーク処理を理解する

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

**主要処理フロー**:
- **162-183行目**: debugBenchmark時の処理
- **163-171行目**: tinybenchインポートとエラーハンドリング
- **172-174行目**: ベンチマーク開始メッセージ
- **175-177行目**: Benchインスタンス作成とタスク追加
- **178行目**: bench.run()実行
- **180-183行目**: 結果の出力

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

```
src/cli/index.js::run()
    │
    ├─ new Context()
    │      │
    │      └─ context.performanceTestFlag（getter）
    │             │
    │             └─ debugBenchmark判定
    │
    ├─ logLevelをdebugに変更
    │
    └─ main()
           │
           └─ formatFiles() / formatStdin()
                  │
                  └─ format()
                         │
                         ├─ tinybench動的インポート
                         │
                         ├─ new Bench()
                         │
                         ├─ bench.add("Format", ...)
                         │
                         ├─ bench.run()
                         │
                         └─ logger.debug()（結果出力）
```

### データフロー図

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

--debug-benchmark ───▶ performanceTestFlag設定 ───▶ debugBenchmark: true
                              │
入力ファイル ─────────▶ format関数
                              │
                              ├─▶ tinybench.Bench()
                              │
                              ├─▶ formatWithCursor()×複数回
                              │
                              └─▶ bench.table() ─────▶ [debug] 測定結果JSON
                                                            │
                                                            └─▶ stderr
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| format.js | `src/cli/format.js` | ソース | ベンチマーク処理の実装 |
| context.js | `src/cli/context.js` | ソース | performanceTestFlagゲッター |
| index.js | `src/cli/index.js` | ソース | CLIエントリーポイント、logLevel変更 |
| logger.js | `src/cli/logger.js` | ソース | ログ出力機能 |
| cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ソース | debugBenchmarkオプション定義 |
