# 機能設計書 18-フォーマットチェック（--check）

## 概要

本ドキュメントは、Prettier CLIにおけるフォーマットチェック機能（--check オプション）について記述する。

### 本機能の処理概要

**業務上の目的・背景**：CI/CD環境やコードレビューにおいて、コードがPrettierの規則に従ってフォーマットされているかを確認する必要がある。--checkオプションは、ファイルを実際に変更せずにフォーマット状態を検証し、人間が読みやすいサマリーメッセージと未フォーマットファイルのパスを出力する。CIパイプラインでの自動検証に最適化されている。

**機能の利用シーン**：
- CI/CDパイプラインでのコードスタイル検証時
- プルリクエストの自動チェック時
- コードレビュー前の自己チェック時
- リンター連携でのフォーマット確認時

**主要な処理内容**：
1. 指定されたファイルパターンの展開
2. 各ファイルのフォーマット状態確認
3. フォーマットされていないファイルのリストアップ
4. サマリーメッセージの生成と出力
5. 終了コードの設定（1: 未フォーマットあり、0: 全てフォーマット済み）

**関連システム・外部連携**：
- prettier.check API関数
- パターン展開システム（expand-patterns.js）
- 無視ファイル処理システム

**権限による制御**：ファイル読み取り権限のみ必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | Usage - Integrating with Linters | 補助機能 | リンターとの連携時のCLIチェックオプションを説明 |
| 13 | Usage - Pre-commit | 補助機能 | pre-commitフックでのチェックモードを説明 |
| 15 | Usage - CLI | 補助機能 | CLIでのフォーマットチェック方法を説明 |
| 18 | Usage - CI | 補助機能 | CI環境での--checkオプション使用方法を説明 |

## 機能種別

検証処理（Read Only）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| filePatterns | string[] | Yes | チェック対象のファイルパターン（glob） | 少なくとも1つ必要 |
| --check / -c | boolean | Yes | チェックモードを有効化 | - |
| --write / -w | boolean | No | 併用時は修正も実行 | - |
| --ignore-path | string[] | No | 無視パターンファイルのパス | 有効なファイルパス |

### 入力データソース

- ファイルシステムからのソースファイル読み込み

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| consoleOutput | string | 処理結果のログ出力（未フォーマットファイル一覧） |
| summaryMessage | string | サマリーメッセージ |
| exitCode | number | 終了コード（0: 全てOK、1: 未フォーマットあり、2: エラー） |

### 出力先

- 標準出力（未フォーマットファイルのパス）
- 標準エラー出力（サマリーメッセージ、エラーメッセージ）

## 処理フロー

### 処理シーケンス

```
1. formatFiles関数内で--checkフラグを確認
   └─ "Checking formatting..." メッセージ出力
2. 各ファイルに対してループ処理
   └─ listDifferent関数を呼び出し
3. listDifferent関数内でprettier.checkを実行
   └─ フォーマット済みかどうかをboolean判定
4. 未フォーマットファイルの場合
   └─ ファイルパスを警告出力
   └─ numberOfUnformattedFilesFoundをインクリメント
5. 全ファイル処理後のサマリー出力
   └─ エラーがある場合: "Error occurred when checking..."
   └─ 全てOKの場合: "All matched files use Prettier code style!"
   └─ 未フォーマットあり: "Code style issues found in X files..."
6. 終了コードの設定
   └─ 未フォーマットあり & !--write → exitCode = 1
```

### フローチャート

```mermaid
flowchart TD
    A[開始: formatFiles with --check] --> B[Checking formatting... 出力]
    B --> C[ファイルループ開始]
    C --> D{ファイル残り?}
    D -->|No| K[サマリー出力]
    D -->|Yes| E[listDifferent呼び出し]
    E --> F[prettier.check実行]
    F --> G{フォーマット済み?}
    G -->|Yes| C
    G -->|No| H{--write?}
    H -->|Yes| I[ファイル修正]
    H -->|No| J[ファイルパス出力]
    I --> C
    J --> C
    K --> L{エラーあり?}
    L -->|Yes| M[Error occurred... 出力]
    L -->|No| N{未フォーマットあり?}
    N -->|No| O[All matched files... 出力]
    N -->|Yes| P{--write?}
    P -->|Yes| Q[Code style issues fixed... 出力]
    P -->|No| R[Code style issues found... 出力]
    M --> S[exitCode設定]
    O --> S
    Q --> S
    R --> S
    S --> T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-018-01 | チェック開始メッセージ | "Checking formatting..."を出力 | --check使用時 |
| BR-018-02 | 未フォーマット判定 | prettier.check()がfalseを返す場合 | 常時 |
| BR-018-03 | 警告出力 | 未フォーマットファイルはlogger.warnで出力 | --check使用時 |
| BR-018-04 | 終了コード1 | 未フォーマットファイルがあり、--write未使用の場合 | 常時 |
| BR-018-05 | --list-different排他 | --checkと--list-different は同時使用不可 | 常時 |

### 計算ロジック

特になし

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

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

データベース操作なし（ファイル読み取りのみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 2 | UndefinedParserError | パーサーが不明 | エラーメッセージ出力、処理継続 |
| 2 | SyntaxError | パースエラー | エラー位置出力、処理継続 |

### リトライ仕様

リトライは行わない（エラーファイルはスキップして継続）

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

トランザクション管理なし（読み取り専用処理）

## パフォーマンス要件

- 単一ファイルチェック: 50ms以下
- 大量ファイルチェック: --cacheオプション併用推奨

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

- ファイル読み取りのみ
- 機密情報の漏洩リスクなし

## 備考

- API関数（prettier.check）としても利用可能
- --writeと併用すると、チェック後に自動修正

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.js | `src/cli/index.js` | --checkと--list-differentの排他チェック |
| 1-2 | cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | --checkオプション定義 |

**主要処理フロー**:
1. **49-51行目（index.js）**: --checkと--list-differentの排他チェック
2. **87-95行目（cli-options.evaluate.js）**: checkオプション定義

#### Step 2: チェック処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | format.js | `src/cli/format.js` | listDifferent関数とformatFiles内の処理 |

**主要処理フロー**:
- **85-100行目**: listDifferent関数 - prettier.checkの呼び出し
- **282-284行目**: "Checking formatting..."の出力
- **459-464行目**: 未フォーマットファイルの警告出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | format.js | `src/cli/format.js` | サマリー出力処理 |

**主要処理フロー**:
- **471-492行目**: サマリーメッセージの条件分岐
- **496-503行目**: 終了コードの設定

#### Step 4: API関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.js | `src/index.js` | prettier.check関数 |

**主要処理フロー**:
- **76-78行目**: check関数の実装（formatと比較）

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

```
prettier [files] --check
    │
    └─ run() [index.js]
           │
           └─ main(context)
                  │
                  ├─ 排他チェック（--check と --list-different）
                  │
                  └─ formatFiles(context) [format.js]
                         │
                         ├─ "Checking formatting..." 出力
                         │
                         └─ for await (expandPatterns())
                                │
                                └─ listDifferent(context, input, options, filename)
                                       │
                                       └─ prettier.check(input, options)
                                              │
                                              └─ format(text, options) === text
```

### データフロー図

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

filePatterns ───▶ expandPatterns() ───▶ filenames[]
                          │
                          ▼
               for each filename
                          │
    file ───▶ fs.readFile() ───▶ input
                          │
                          ▼
               prettier.check()
                          │
                          ├─ format(input) ───▶ output
                          │
                          └─ input === output?
                                   │
                          ┌───────┴───────┐
                          │               │
                        [true]          [false]
                          │               │
                          ▼               ▼
                       (skip)     logger.warn(filename)
                                         │
                                         ▼
                              numberOfUnformattedFilesFound++
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/cli/index.js` | ソース | CLIエントリーポイント、排他チェック |
| format.js | `src/cli/format.js` | ソース | listDifferent関数、サマリー出力 |
| cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ソース | --checkオプション定義 |
| index.js | `src/index.js` | ソース | prettier.check API関数 |
| expand-patterns.js | `src/cli/expand-patterns.js` | ソース | ファイルパターン展開 |
| logger.js | `src/cli/logger.js` | ソース | ログ出力（warn使用） |
