# 機能設計書 19-差分表示（--list-different）

## 概要

本ドキュメントは、Prettier CLIにおける差分表示機能（--list-different オプション）について記述する。

### 本機能の処理概要

**業務上の目的・背景**：CI/CDスクリプトやシェルスクリプトにおいて、Prettierでフォーマットされていないファイルの一覧を取得する必要がある。--list-differentオプションは、フォーマットが必要なファイルの名前のみを出力する。--checkとは異なり、サマリーメッセージを出力せず、スクリプトでの処理に適した形式でファイルパスを出力する。

**機能の利用シーン**：
- シェルスクリプトでの未フォーマットファイル一覧取得時
- パイプ処理での後続ツールへの入力生成時
- CI/CDでのファイル一覧取得時
- 差分ファイルに対する追加処理のトリガー取得時

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

**関連システム・外部連携**：
- prettier.check API関数
- パターン展開システム（expand-patterns.js）
- listDifferent関数との共有処理

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | Usage - CLI | 補助機能 | CLIでの差分ファイル一覧表示を説明 |
| 18 | Usage - CI | 補助機能 | CI環境での--list-differentオプション使用方法を説明 |

## 機能種別

検証処理（Read Only）

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| consoleOutput | string | 未フォーマットファイルのパス（1行1ファイル） |
| exitCode | number | 終了コード（0: 全てOK、1: 未フォーマットあり、2: エラー） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. formatFiles関数内で--listDifferentフラグを確認
   └─ --checkと異なりサマリーメッセージは出力しない
2. 各ファイルに対してループ処理
   └─ listDifferent関数を呼び出し
3. listDifferent関数内でprettier.checkを実行
   └─ フォーマット済みかどうかをboolean判定
4. 未フォーマットファイルの場合
   └─ ファイルパスをlogger.logで出力
   └─ process.exitCode = 1を設定
5. 全ファイル処理後
   └─ サマリー出力なし
   └─ 終了コードは既に設定済み
```

### フローチャート

```mermaid
flowchart TD
    A[開始: formatFiles with --list-different] --> B[ファイルループ開始]
    B --> C{ファイル残り?}
    C -->|No| H[終了]
    C -->|Yes| D[listDifferent呼び出し]
    D --> E[prettier.check実行]
    E --> F{フォーマット済み?}
    F -->|Yes| B
    F -->|No| G[ファイルパス出力 + exitCode=1]
    G --> B
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-019-01 | シンプル出力 | ファイルパスのみ出力（サマリーなし） | --list-different使用時 |
| BR-019-02 | 即時終了コード設定 | 未フォーマット検出時に即座にexitCode=1 | 常時 |
| BR-019-03 | logger.log使用 | logger.warnではなくlogger.logで出力 | --list-different使用時 |
| BR-019-04 | --check排他 | --checkと--list-different は同時使用不可 | 常時 |
| BR-019-05 | --write併用可能 | 差分表示しつつ修正も実行可能 | --write併用時 |

### 計算ロジック

特になし

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

- 単一ファイルチェック: 50ms以下
- --checkと同等のパフォーマンス

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

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

## 備考

- --checkよりもスクリプト処理に適している
- 出力をパイプで他のコマンドに渡すユースケースを想定

---

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

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

### 推奨読解順序

#### 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` | --list-differentオプション定義 |

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

#### Step 2: 差分表示処理を理解する

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

**主要処理フロー**:
- **85-100行目**: listDifferent関数
- **86-88行目**: --check || --listDifferentの判定
- **92-93行目**: ファイルパスのlogger.log出力とexitCode設定
- **461-463行目**: --list-different時のファイル名出力

#### Step 3: --checkとの違いを理解する

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

**主要処理フロー**:
- **459-460行目**: --check時はlogger.warn、--list-different時はlogger.log
- **471行目**: サマリー出力はcontext.argv.checkの場合のみ

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

```
prettier [files] --list-different
    │
    └─ run() [index.js]
           │
           └─ main(context)
                  │
                  ├─ 排他チェック（--check と --list-different）
                  │
                  └─ formatFiles(context) [format.js]
                         │
                         └─ for await (expandPatterns())
                                │
                                └─ listDifferent(context, input, options, filename)
                                       │
                                       ├─ prettier.check(input, options)
                                       │
                                       └─ !result && !--write
                                              │
                                              ├─ logger.log(filename)
                                              └─ process.exitCode = 1
```

### データフロー図

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

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

### 関連ファイル一覧

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