# 通知設計書 15-No matching files

## 概要

本ドキュメントは、Prettier CLI においてグロブパターンに一致するファイルが1つも見つからなかった場合に表示されるエラー通知「No matching files」について定義する設計書である。

### 本通知の処理概要

Prettier CLI がファイルパターン（グロブパターンまたはファイルパス）を展開した結果、対象となるファイルが1つも見つからなかった場合、ユーザーに対してエラー内容を通知する。この通知により、ユーザーは指定したパターンが適切でないこと、または対象ファイルが存在しないことを把握できる。

**業務上の目的・背景**：開発者がコードフォーマットを実行する際、対象ファイルを正しく指定することは重要である。パターンの記述ミスやファイル構成の変更により、意図したファイルがマッチしない場合がある。この通知により、ユーザーはパターンの問題を早期に発見し、コマンドを修正できる。CI/CDパイプラインでは、このエラーにより設定ミスを検出できる。

**通知の送信タイミング**：`prettier` コマンドを実行し、すべてのファイルパターンを展開した結果、1つもファイルが見つからなかった場合に通知される。具体的には、`expand-patterns.js` の `expandPatterns` 関数内で `noResults === true` かつ `errorOnUnmatchedPattern !== false` の条件を満たした時点で出力される（行38-43）。

**通知の受信者**：CLI を実行している開発者またはCI/CDシステム。標準エラー出力（stderr）に出力されるため、ターミナルで実行している場合はリアルタイムで表示され、パイプライン実行時はエラーログとして記録される。

**通知内容の概要**：「No matching files.」という固定メッセージと、指定されたファイルパターンの一覧で構成される。

**期待されるアクション**：この通知を受け取った場合、ユーザーは以下のアクションを検討する必要がある。(1) 指定したグロブパターンを確認、(2) 対象ファイルが存在するディレクトリを確認、(3) ファイル拡張子が正しいか確認、(4) ネガティブパターン（!で始まるパターン）により除外されていないか確認。

## 通知種別

CLI 標準エラー出力（エラー通知）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（パターン展開完了時に出力） |
| 優先度 | 高（エラー通知） |
| リトライ | なし |

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

CLI 実行環境の標準エラー出力（`process.stderr`）に対して直接出力する。ログレベルが `error` 以上に設定されている場合のみ出力される（デフォルトで有効）。`--error-on-unmatched-pattern=false` オプションが指定されている場合はこの通知は抑止される。

## 通知テンプレート

### CLI出力通知の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | 標準エラー出力（stderr） |
| 形式 | テキスト |
| カラー | プレフィックス `[error]` は赤色（picocolors.red） |

### 本文テンプレート

```
[error] No matching files. Patterns: {パターン1} {パターン2} ...
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| context.filePatterns | 指定されたファイルパターンの配列 | コマンドライン引数から取得 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| パターン展開 | ファイル検索結果なし | すべてのパターンを展開した結果、1つもファイルが見つからなかった場合 | `noResults === true` で判定 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `--error-on-unmatched-pattern=false` | このオプションを指定するとパターン不一致エラーが抑止される |
| ログレベルが `error` 未満 | `--log-level silent` 指定時は出力されない |
| 1つ以上のファイルがマッチ | 少なくとも1つのファイルが見つかればこのエラーは発生しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[expandPatterns開始] --> B[パターンごとにループ]
    B --> C[パターン種別判定]
    C -->|ファイル| D[lstatSafe実行]
    C -->|ディレクトリ| E[ディレクトリ展開]
    C -->|グロブ| F[fastGlob実行]
    D --> G{ファイル存在?}
    E --> H[結果yield]
    F --> H
    G -->|Yes| H
    G -->|No| I[エラーyield]
    H --> J[noResults = false]
    I --> J
    J --> K[次のパターン]
    K --> B
    B -->|完了| L{noResults?}
    L -->|true| M{errorOnUnmatchedPattern?}
    M -->|true| N[No matching files エラーyield]
    M -->|false| O[終了]
    L -->|false| O
    N --> O
```

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

### 参照テーブル一覧

本通知はデータベースを使用しない。ファイルシステムのみを参照する。

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | N/A | N/A |

### テーブル別参照項目詳細

該当なし

### 更新テーブル一覧

該当なし

#### 送信ログテーブル

本通知ではログテーブルへの記録は行わない。

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| パターン不一致 | 指定したパターンにマッチするファイルがない | パターンを修正するか、対象ファイルを作成 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（CLI実行時に即座に出力）

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

- 指定されたファイルパターンがコンソールに出力されるため、機密性の高いパス情報が含まれる場合は注意が必要
- 標準エラー出力への出力のみであり、ネットワーク送信は行わない

## 備考

- このエラーは `expandPatterns` ジェネレータ関数の最後で生成される
- `format.js` の `formatFiles` 関数内でエラーとして処理され、`process.exitCode = 2` が設定される
- パターンはスペース区切りで連結して表示される

---

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

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

### 推奨読解順序

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

ファイルパターンの構造と、パターン展開の結果オブジェクトを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | expand-patterns.js | `src/cli/expand-patterns.js` | パターン展開結果のyieldオブジェクト構造（error, filePath, ignoreUnknown） |

**読解のコツ**: `expandPatterns` はジェネレータ関数であり、`yield` で結果を逐次返却する。`error` プロパティが存在する場合はエラー、`filePath` が存在する場合は正常なファイルパス。

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

パターン展開のメインロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | expand-patterns.js | `src/cli/expand-patterns.js` | `expandPatterns` 関数の全体フロー（行14-44） |

**主要処理フロー**:
1. **行15**: `seen` セット（重複排除用）と `noResults` フラグの初期化
2. **行18-36**: `expandPatternsInternal` からの結果をイテレート
3. **行21**: `noResults = false` で結果ありを記録
4. **行38-42**: `noResults === true` かつ `errorOnUnmatchedPattern !== false` の場合にエラーをyield

#### Step 3: エラー処理を理解する

format.js でのエラーハンドリングを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | format.js | `src/cli/format.js` | expandPatterns からのエラー処理（行305-313） |

**主要処理フロー**:
- **行308-312**: `error` プロパティが存在する場合、`context.logger.error(error)` で出力し、`process.exitCode = 2` を設定

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

```
src/cli/format.js::formatFiles()  [行272]
    │
    └─ expandPatterns()  [src/cli/expand-patterns.js:14]
           │
           ├─ expandPatternsInternal()  [行49]
           │      │
           │      ├─ パターン種別判定
           │      │      ├─ ファイル → lstatSafe()
           │      │      ├─ ディレクトリ → glob展開
           │      │      └─ グロブ → fastGlob()
           │      │
           │      └─ yield { filePath, ignoreUnknown }
           │             または yield { error }
           │
           └─ noResults チェック [行38]
                  │
                  └─ yield { error: "No matching files..." }  [行40-42]
                         │
                         ▼
              format.js で context.logger.error() [行309]
```

### データフロー図

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

filePatterns ─────────▶ expandPatternsInternal()
(コマンドライン引数)           │
                              ▼
                         各パターンを展開
                              │
                              ▼
                         [結果なし]
                              │
                              ▼
                         noResults === true
                              │
                              ▼
                         errorOnUnmatchedPattern チェック
                              │
                              ▼
                         [有効]
                              │
                              ▼
                         yield { error }
                              │
                              ▼
                         format.js で処理
                              │
                              ▼
                         "[error] No matching files. Patterns: {パターン}"
                              │
                              ▼
                         標準エラー出力 (stderr)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| expand-patterns.js | `src/cli/expand-patterns.js` | ソース | パターン展開とエラー生成 |
| format.js | `src/cli/format.js` | ソース | エラーのログ出力とexitCode設定 |
| logger.js | `src/cli/logger.js` | ソース | エラーログ出力機能 |
| context.js | `src/cli/context.js` | ソース | filePatterns等のコンテキスト管理 |
| utilities.js | `src/cli/utilities.js` | ソース | lstatSafe関数等 |
