# 通知設計書 35-Performance-test-skipped-output

## 概要

本ドキュメントは、Prettier CLIのパフォーマンステストオプション（`--debug-benchmark`、`--debug-repeat`、または環境変数`PRETTIER_PERF_REPEAT`）使用時に出力される、通常の出力スキップを通知するログメッセージの設計仕様を記載する。

### 本通知の処理概要

本通知は、パフォーマンステストモードにおいて通常のコード出力やファイル書き込みがスキップされることをユーザーに通知するデバッグログメッセージを出力する機能を提供する。

**業務上の目的・背景**：Prettierのパフォーマンステストモードは、フォーマット処理の速度を測定・分析するために使用される。このモードでは純粋なフォーマット処理のパフォーマンスのみを測定するため、結果の出力やファイル書き込みといったI/O処理を意図的にスキップする。この通知により、ユーザーは出力がスキップされている理由を理解でき、テストが正常に動作していることを確認できる。

**通知の送信タイミング**：フォーマット処理の完了後、結果を出力する直前のタイミングで出力される。標準入力フォーマット時とファイルフォーマット時の両方で同様のメッセージが出力される。

**通知の受信者**：パフォーマンステストを実行しているPrettier開発者またはパフォーマンス分析を行うユーザー。

**通知内容の概要**：パフォーマンステストオプション名を含む以下のいずれかのメッセージが出力される：
- stdin処理時：「'{オプション名}' option found, skipped print code to screen.」
- ファイル処理時：「'{オプション名}' option found, skipped print code or write files.」

**期待されるアクション**：本通知は情報提供を目的としており、特別なアクションは不要。パフォーマンス測定結果は別途デバッグログとして出力される。

## 通知種別

CLIデバッグログ出力（stdoutまたはstderr）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 低 |
| リトライ | 無し |

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

ロガーの`log`メソッドを経由してstdoutに出力される。パフォーマンステストモードでは`--log-level`が自動的に`debug`に引き上げられる（index.js 28-30行目）ため、通常は表示される。

## 通知テンプレート

### CLI出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | stdout |
| プレフィックス | なし |
| 色 | なし（デフォルト） |

### 本文テンプレート

stdin処理時：
```
'{performanceTestFlag.name}' option found, skipped print code to screen.
```

ファイル処理時：
```
'{performanceTestFlag.name}' option found, skipped print code or write files.
```

### performanceTestFlag.name の値

| オプション | 名前 |
|----------|------|
| --debug-benchmark | `--debug-benchmark` |
| --debug-repeat | `--debug-repeat` |
| 環境変数 PRETTIER_PERF_REPEAT | `PRETTIER_PERF_REPEAT (environment variable)` |

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| performanceTestFlag.name | パフォーマンステストオプション名 | context.performanceTestFlag.name | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| stdin処理完了 | formatStdinでのフォーマット完了後 | `performanceTestFlag`が存在する | パフォーマンステストモード有効時 |
| ファイル処理 | formatFilesでの各ファイルフォーマット完了後 | `performanceTestFlag`が存在する | パフォーマンステストモード有効時（最初のファイルで発動後return） |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| パフォーマンステストオプションが未指定の場合 | performanceTestFlagがundefined |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[フォーマット処理完了] --> B{performanceTestFlag<br>が存在する?}
    B -->|No| C[通常の出力処理]
    B -->|Yes| D[スキップ通知生成]
    D --> E[logger.log呼び出し]
    E --> F[return で処理終了]
    F --> G[以降の出力処理はスキップ]
```

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

### 参照テーブル一覧

該当なし（CLIツールのためデータベースは使用しない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

本通知は情報提供のみを目的としており、エラーケースは想定しない。

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（リトライ無し） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

該当なし（CLI同期処理のため）

### 配信時間帯

該当なし（CLI実行時即座に出力）

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

本通知は固定メッセージとオプション名のみを出力し、ユーザー入力やファイル内容を含まないため、セキュリティ上の考慮事項は特にない。

## 備考

- `--debug-benchmark`はtinybenchライブラリを使用して詳細なベンチマーク測定を行う
- `--debug-repeat`は指定回数フォーマットを繰り返し実行し、平均処理時間を測定する
- 環境変数`PRETTIER_PERF_REPEAT`は数値文字列として指定する
- パフォーマンステストモードではログレベルが自動的にdebugに引き上げられる
- ファイルモードの場合、最初のファイル処理完了時点でreturnするため、複数ファイル指定時も1ファイルのみ処理される
- パフォーマンス測定結果自体は`logger.debug`を通じて別途出力される

---

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

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

### 推奨読解順序

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

performanceTestFlagの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | context.js | `src/cli/context.js` | performanceTestFlagゲッターの実装（58-85行目） |

**読解のコツ**: performanceTestFlagはゲッターとして実装されており、`debugBenchmark`、`debugRepeat`、環境変数の順で優先度が判定される。

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

ログレベル自動引き上げとスキップ通知の場所を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/cli/index.js` | ログレベル自動引き上げ処理（28-30行目） |
| 2-2 | format.js | `src/cli/format.js` | stdin処理時のスキップ通知（258-264行目） |
| 2-3 | format.js | `src/cli/format.js` | ファイル処理時のスキップ通知（404-408行目） |

**主要処理フロー**:
1. **index.js 28-30行目**: performanceTestFlag存在時にログレベルをdebugに変更
2. **format.js 258-264行目**: stdin処理完了後のスキップ通知
3. **format.js 404-408行目**: ファイル処理完了後のスキップ通知とreturn

#### Step 3: パフォーマンステスト処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | format.js | `src/cli/format.js` | format関数内のベンチマーク・リピート処理（161-208行目） |

**主要処理フロー**:
- **162-183行目**: `debugBenchmark`時のtinybench使用
- **184-208行目**: `debugRepeat`時の繰り返し実行と平均計算

#### Step 4: オプション定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | debugBenchmark/debugRepeatオプション定義（138-159行目） |

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

```
run (src/cli/index.js:13)
    │
    ├─ context.performanceTestFlag (getter)
    │      ├─ debugBenchmark → { name: "--debug-benchmark", debugBenchmark: true }
    │      ├─ debugRepeat → { name: "--debug-repeat", debugRepeat: N }
    │      └─ PRETTIER_PERF_REPEAT → { name: "PRETTIER_PERF_REPEAT...", debugRepeat: N }
    │
    ├─ ログレベル引き上げ (28-30行目)
    │
    └─ main
           │
           ├─ formatStdin (src/cli/format.js:225)
           │      └─ format → performanceTestFlag
           │             └─ logger.log("skipped print code to screen")
           │                    └─ return (258-264行目)
           │
           └─ formatFiles (src/cli/format.js:272)
                  └─ ファイルループ
                         └─ format → performanceTestFlag
                                └─ logger.log("skipped print code or write files")
                                       └─ return (404-408行目)
```

### データフロー図

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

--debug-benchmark
--debug-repeat N      ───▶  context.performanceTestFlag
PRETTIER_PERF_REPEAT          ↓
                         { name, debugBenchmark/debugRepeat }
                              ↓
                         formatStdin/formatFiles
                              ↓
                         format処理実行
                              ↓
                         performanceTestFlag存在
                              ↓
                         logger.log ───────────▶ stdout: "'--debug-xxx' option found..."
                              ↓
                         return (出力スキップ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| context.js | `src/cli/context.js` | ソース | performanceTestFlagゲッター |
| index.js | `src/cli/index.js` | ソース | ログレベル自動引き上げ |
| format.js | `src/cli/format.js` | ソース | スキップ通知出力、ベンチマーク/リピート処理 |
| cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ソース | debugBenchmark/debugRepeatオプション定義 |
| logger.js | `src/cli/logger.js` | ソース | ログ出力機能 |
