# 帳票設計書 10-チェック結果サマリー

## 概要

本ドキュメントは、フォーマットチェックの結果サマリーを標準出力へ出力する帳票「チェック結果サマリー」の設計仕様を定義する。

### 本帳票の処理概要

**業務上の目的・背景**：CI/CDパイプラインやプルリクエストのチェックにおいて、コードがPrettierのフォーマットルールに準拠しているかを検証することは品質管理の重要な要素である。本帳票は、`--check`オプション使用時にフォーマットチェックの結果をサマリー形式で出力し、チェックの成否と該当ファイル数を明確に伝える。これにより、開発者やCIシステムがフォーマット状態を迅速に把握できる。

**帳票の利用シーン**：CI/CDパイプラインでのフォーマットチェック、プルリクエストの自動検証、開発者によるローカルチェック、コードレビュー前の事前確認など。

**主要な出力内容**：
1. チェック開始メッセージ
2. フォーマット差異のあるファイル一覧（警告）
3. 結果サマリーメッセージ

**帳票の出力タイミング**：CLIで`--check`オプションを指定した際に出力される。

**帳票の利用者**：開発者、CI/CDシステム、コードレビュアー、品質管理担当者

## 帳票種別

ステータス出力

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| CLI-01 | コマンドライン | `prettier --check [files]` | コマンド実行 |
| CLI-02 | コマンドライン | `prettier --check --write [files]` | コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト |
| 出力先 | 標準出力（log）/ 標準エラー出力（warn） |
| 文字コード | UTF-8 |
| 色付け | picocolors使用（TTY環境） |

### 出力パターン

#### 全ファイルフォーマット済みの場合
```
Checking formatting...
All matched files use Prettier code style!
```

#### フォーマット差異がある場合
```
Checking formatting...
[warn] file1.js
[warn] file2.js
[warn] Code style issues found in 2 files. Run Prettier with --write to fix.
```

#### --writeと併用した場合
```
Checking formatting...
[warn] file1.js
[warn] file2.js
[warn] Code style issues fixed in 2 files.
```

#### エラーが発生した場合
```
Checking formatting...
[error] file1.js: SyntaxError: ...
Error occurred when checking code style in 1 file.
```

## 帳票レイアウト

### レイアウト概要

出力は開始メッセージ、ファイル一覧、サマリーで構成される。

```
┌─────────────────────────────────────┐
│  Checking formatting...              │（開始メッセージ）
├─────────────────────────────────────┤
│  [warn] file1.js                     │（差異ファイル、警告レベル）
│  [warn] file2.js                     │
│  ...                                 │
├─────────────────────────────────────┤
│  [warn] Code style issues found...   │（サマリー、警告レベル）
└─────────────────────────────────────┘
```

### 出力項目

| No | 項目名 | 説明 | 出力レベル | 条件 |
|----|-------|------|----------|------|
| 1 | 開始メッセージ | "Checking formatting..." | log | 常に |
| 2 | 差異ファイル | フォーマット差異のあるファイルパス | warn | 差異あり時 |
| 3 | 成功メッセージ | "All matched files use Prettier code style!" | log | 差異なし時 |
| 4 | 差異サマリー | "Code style issues found/fixed in X files." | warn | 差異あり時 |
| 5 | エラーサマリー | "Error occurred when checking code style in X files." | log | エラー発生時 |

### メッセージ詳細

| 状態 | メッセージ | 終了コード |
|------|----------|----------|
| 全ファイルOK | All matched files use Prettier code style! | 0 |
| 差異あり（--write未指定） | Code style issues found in {N} files. Run Prettier with --write to fix. | 1 |
| 差異あり（--write指定） | Code style issues fixed in {N} files. | 0 |
| エラー発生 | Error occurred when checking code style in {N} files. | 2 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| ファイルパターン | チェック対象のファイル | Yes |
| --check | チェックモード有効化 | Yes |

### 処理条件

| 条件 | 処理 |
|------|------|
| performanceTestFlag設定時 | 開始メッセージをスキップ |
| ファイル差異あり | warn出力、exitCode=1 |
| パースエラー | error出力、exitCode=2 |
| --write併用時 | 差異ファイルを修正 |

## データフロー仕様

### 入力データ

| データ項目 | 型 | 説明 |
|-----------|-----|------|
| context.argv.check | boolean | チェックモードフラグ |
| context.argv.write | boolean | ファイル書き込みフラグ |
| numberOfUnformattedFilesFound | number | 差異ファイル数 |
| numberOfFilesWithError | number | エラーファイル数 |

### 出力データ

| データ項目 | 型 | 説明 |
|-----------|-----|------|
| サマリーメッセージ | string | 結果を表すメッセージ |
| process.exitCode | number | 終了コード（0, 1, 2） |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[formatFiles開始] --> B{--check?}
    B -->|Yes| C{performanceTestFlag?}
    C -->|No| D["logger.log('Checking formatting...')"]
    C -->|Yes| E[スキップ]
    D --> F[ファイルループ処理]
    E --> F
    F --> G{フォーマット差異?}
    G -->|Yes| H["logger.warn(filename)"]
    G -->|No| I[次のファイル]
    H --> I
    I --> J{全ファイル処理完了?}
    J -->|No| F
    J -->|Yes| K[サマリー出力]
    K --> L{エラーあり?}
    L -->|Yes| M[エラーサマリー出力]
    L -->|No| N{差異ファイルあり?}
    N -->|No| O[成功メッセージ出力]
    N -->|Yes| P{--write?}
    P -->|Yes| Q[修正完了メッセージ]
    P -->|No| R[差異検出メッセージ]
    B -->|No| S[通常処理]
```

### 終了コード決定フロー

```mermaid
flowchart TD
    A[処理完了] --> B{エラー発生?}
    B -->|Yes| C[exitCode = 2]
    B -->|No| D{差異あり?}
    D -->|No| E[exitCode = 0]
    D -->|Yes| F{--write?}
    F -->|Yes| G[exitCode = 0]
    F -->|No| H[exitCode = 1]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 終了コード |
|----------|---------|--------------|----------|
| パースエラー | 構文エラー | {filename}: SyntaxError: {message} | 2 |
| ファイル読み取りエラー | アクセス不可 | Unable to read file "{filename}" | 2 |
| 設定エラー | 設定値不正 | Invalid {option} value. | exit(1) |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 処理方式 | 非同期処理（async/await） |
| 並列処理 | ファイルは順次処理 |
| キャッシュ | --cacheオプションで有効化可能 |

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

- ファイルパスが出力に含まれる
- エラーメッセージにソースコードの一部が含まれる可能性

## 備考

- --checkと--list-differentは同時使用不可
- --checkと--writeは併用可能（修正して結果を報告）
- ファイル数が1の場合は"the above file"、複数の場合は"{N} files"と表示

---

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

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

### 推奨読解順序

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

まず、チェック結果の状態変数を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | format.js | `src/cli/format.js` | 状態変数定義（278-279行目） |

**読解のコツ**: `numberOfUnformattedFilesFound`と`numberOfFilesWithError`で結果を追跡。

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

チェック処理の起点を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | format.js | `src/cli/format.js` | formatFiles関数（272-504行目） |
| 2-2 | format.js | `src/cli/format.js` | --check開始メッセージ（282-284行目） |

**主要処理フロー**:
1. **282-284行目**: "Checking formatting..."出力
2. **459-465行目**: 差異ファイルの警告出力
3. **471-493行目**: サマリー出力

#### Step 3: 差異検出処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | format.js | `src/cli/format.js` | 差異判定（398行目） |
| 3-2 | format.js | `src/cli/format.js` | 差異カウント（464行目） |

**主要処理フロー**:
- **398行目**: `isDifferent = output !== input`
- **459行目**: checkモード時の警告出力
- **464行目**: カウントインクリメント

#### Step 4: サマリー出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | format.js | `src/cli/format.js` | サマリー出力（471-493行目） |

**主要処理フロー**:
- **472-479行目**: エラー発生時のメッセージ
- **480-481行目**: 差異なし時のメッセージ
- **482-492行目**: 差異あり時のメッセージ

#### Step 5: 終了コード設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | format.js | `src/cli/format.js` | exitCode設定（496-503行目） |

**主要処理フロー**:
- **496-503行目**: --check/--list-different時のexitCode設定

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

```
CLI: formatFiles() [src/cli/format.js:272]
    │
    ├─ logger.log("Checking formatting...") [282-284行目]
    │
    ├─ ファイルループ処理
    │      │
    │      ├─ prettier.format() / prettier.check()
    │      │
    │      ├─ (差異あり時)
    │      │      └─ logger.warn(filename) [459行目]
    │      │
    │      └─ numberOfUnformattedFilesFound++ [464行目]
    │
    └─ サマリー出力 [471-493行目]
           │
           ├─ (エラーあり時)
           │      └─ logger.log("Error occurred...")
           │
           ├─ (差異なし時)
           │      └─ logger.log("All matched files...")
           │
           └─ (差異あり時)
                  └─ logger.warn("Code style issues...")
```

### データフロー図

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

ファイルパターン ────────▶ expandPatterns()
                              │
                              ▼
                    "Checking formatting..." ──────▶ 標準出力
                              │
                              ▼
                    ファイル毎のフォーマット
                              │
                              ├─ (差異あり)
                              │      │
                              │      ▼
                              │  "[warn] filename" ──────▶ 標準エラー
                              │      │
                              │      ▼
                              │  numberOfUnformattedFilesFound++
                              │
                              ├─ (エラー)
                              │      │
                              │      ▼
                              │  numberOfFilesWithError++
                              │
                              └─ (処理完了)
                                     │
                                     ▼
                              サマリーメッセージ ──────▶ 標準出力/エラー
                                     │
                                     ▼
                              process.exitCode設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| format.js | `src/cli/format.js` | ソース | formatFiles関数、サマリー出力 |
| logger.js | `src/cli/logger.js` | ソース | log, warn出力 |
| index.js | `src/cli/index.js` | ソース | --checkオプション検証 |
| prettier-internal.js | `src/cli/prettier-internal.js` | ソース | picocolors取得 |
