# 通知設計書 20-No files matching the pattern were found

## 概要

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

### 本通知の処理概要

Prettier CLI がグロブパターン（ワイルドカードを含むパターン、例: `**/*.ts`）として認識されたパターンに対してファイル検索を実行した結果、対象となるファイルが1つも見つからなかった場合、ユーザーに対してエラー内容を通知する。この通知は、パターン自体は構文的に正しいが、現在のファイルシステムの状態ではマッチするファイルが存在しない場合に発生する。

**業務上の目的・背景**：開発者がグロブパターンを使用してコードフォーマットを実行する際、対象ファイルが存在することは処理の前提条件である。パターンのタイポ、ファイル構成の変更、または誤った拡張子の指定により意図したファイルがマッチしない場合、ユーザーに明確なフィードバックを提供することで、パターンの確認を促す。

**通知の送信タイミング**：`prettier` コマンドを実行し、グロブパターンとして認識されたパターンに対して `fastGlob()` を実行した結果、マッチするファイルが0件だった場合に通知される。具体的には、`expand-patterns.js` の `expandPatternsInternal` 関数内で `result.length === 0` かつ `errorOnUnmatchedPattern !== false` の条件を満たした時点で出力される（行129-131）。

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

**通知内容の概要**：「No files matching the pattern were found」という固定メッセージと、対象となったグロブパターンで構成される。

**期待されるアクション**：この通知を受け取った場合、ユーザーは以下のアクションを検討する必要がある。(1) グロブパターンの構文が正しいか確認、(2) 対象ファイルが存在するか確認、(3) ファイルの拡張子がパターンと一致しているか確認、(4) 無視パターンによりファイルが除外されていないか確認。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（グロブ展開完了時に出力） |
| 優先度 | 高（エラー通知） |
| リトライ | なし（一度きりの出力、ただし処理は継続） |

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

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

## 通知テンプレート

### CLI出力通知の場合

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

### 本文テンプレート

```
[error] No files matching the pattern were found: "{パターン}".
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| input | 元のグロブパターン | コマンドライン引数から取得 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| パターン展開 | グロブパターン展開結果なし | `type === "glob"` のエントリに対して `fastGlob()` の結果が0件かつ `errorOnUnmatchedPattern !== false` | `result.length === 0` で判定 |

### 送信抑止条件

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

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[expandPatternsInternal開始] --> B[パターンごとにループ]
    B --> C{パターン種別?}
    C -->|グロブ| D{lstatSafe結果?}
    D -->|null| E{pattern[0] === '!'?}
    E -->|No| F[type: glob エントリ作成]
    E -->|Yes| G[ネガティブパターンとしてignoreに追加]
    F --> H[fastGlob実行]
    H -->|成功| I{result.length?}
    I -->|> 0| J[結果yield]
    I -->|=== 0| K{errorOnUnmatchedPattern?}
    K -->|true| L[errorMessages.emptyResults.glob メッセージ生成]
    L --> M[yield error]
    K -->|false| N[何もしない]
    C -->|ファイル| O[type: file エントリ作成]
    C -->|ディレクトリ| P[type: dir エントリ作成]
    J --> Q[終了]
    M --> R[次のパターンへ]
    N --> R
    G --> R
    O --> H
    P --> H
    R --> B
```

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

### 参照テーブル一覧

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

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

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

該当なし

### 更新テーブル一覧

該当なし

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

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| パターン不一致 | 指定したグロブパターンにマッチするファイルがない | パターンまたはファイル構成を確認 |
| 拡張子不一致 | パターンの拡張子と実際のファイルの拡張子が異なる | 正しい拡張子を指定 |
| パス不一致 | パターンのディレクトリ構造と実際の構造が異なる | パスを確認 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

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

## 備考

- このエラーは `type === "glob"` のエントリ（グロブパターンとして認識されたパターン）に対してのみ発生する
- ネガティブパターン（`!` で始まるパターン）はグロブエントリとして作成されないため、このエラーは発生しない
- `dot: true` がデフォルト設定であり、ドットファイル（`.eslintrc` 等）もマッチ対象となる
- 処理は中断されず、次のパターンの処理に継続する
- `format.js` でエラーを受け取り、`process.exitCode = 2` が設定される
- エラーメッセージは `errorMessages.emptyResults.glob` として定義されている（行148）

---

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

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

### 推奨読解順序

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

パターンエントリの構造とエラーメッセージの定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | expand-patterns.js | `src/cli/expand-patterns.js` | エントリオブジェクト構造とerrorMessages.emptyResults定義（行145-149） |

**読解のコツ**: `errorMessages.emptyResults` オブジェクトには `file`, `dir`, `glob` の3種類のメッセージが定義されている。`type === "glob"` の場合は "No files matching the pattern were found" が使用される。

#### Step 2: グロブパターン判定を理解する

パターンがグロブパターンとして判定される条件を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | expand-patterns.js | `src/cli/expand-patterns.js` | グロブパターン判定（行104-113）と結果判定（行129-131） |

**主要処理フロー**:
1. **行71**: `lstatSafe(absolutePath)` の結果が `null`（存在しない）
2. **行104**: `pattern[0] !== "!"` でネガティブパターンでないことを確認
3. **行107-112**: `type: "glob"` エントリを作成
4. **行129**: `result.length === 0` で結果なしを判定
5. **行130-131**: `errorOnUnmatchedPattern !== false` の場合にエラーをyield

#### Step 3: グロブオプションを理解する

fastGlobに渡されるオプションを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | expand-patterns.js | `src/cli/expand-patterns.js` | globOptions の設定（行54-58） |

**主要オプション**:
- **行55**: `dot: true` - ドットファイルもマッチ
- **行57**: `followSymbolicLinks: false` - シンボリックリンクは追跡しない

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

```
src/cli/expand-patterns.js::expandPatternsInternal()  [行49]
    │
    ├─ globOptions設定 [行54-58]
    │      ├─ dot: true
    │      └─ followSymbolicLinks: false
    │
    ├─ パターンごとにループ [行64]
    │      │
    │      ├─ lstatSafe(absolutePath)  [行71]
    │      │      └─ [stat === null]
    │      │
    │      └─ pattern[0] !== "!" [行104以降]
    │             │
    │             └─ entries.push({ type: "glob", ... })  [行107-112]
    │
    └─ エントリごとにループ [行116]
           │
           ├─ fastGlob(glob, globOptions)  [行120]
           │      │
           │      └─ result.length === 0  [行129]
           │             │
           │             └─ errorOnUnmatchedPattern !== false
           │                    │
           │                    └─ yield { error }  [行131]
           │                           │
           │                           ▼
           │                    format.js で処理 [行308-312]
           │
           └─ yield* sortPaths(result)  [行134]
```

### データフロー図

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

グロブパターン ────────▶ lstatSafe()
(例: **/*.ts)                  │
                              ▼
                         [stat === null]
                              │
                              ▼
                         pattern[0] !== "!" チェック
                              │
                              ▼
                         type: "glob" エントリ作成
                              │
                              ▼
                         fastGlob(glob, { dot: true }) 実行
                              │
                              ▼
                         [result.length === 0]
                              │
                              ▼
                         errorOnUnmatchedPattern チェック
                              │
                              ▼
                         [有効]
                              │
                              ├─ errorMessages.emptyResults.glob 取得
                              │
                              ▼
                         yield { error }
                              │
                              ▼
                         format.js で context.logger.error()
                              │
                              ▼
                         "[error] No files matching the pattern were found: \"{パターン}\"."
                              │
                              ▼
                         標準エラー出力 (stderr)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| expand-patterns.js | `src/cli/expand-patterns.js` | ソース | パターン展開とエラー生成 |
| format.js | `src/cli/format.js` | ソース | エラーのログ出力とexitCode設定 |
| logger.js | `src/cli/logger.js` | ソース | エラーログ出力機能 |
| utilities.js | `src/cli/utilities.js` | ソース | lstatSafe関数 |
| prettier-internal.js | `src/cli/prettier-internal.js` | ソース | fastGlobのエクスポート |
| directory-ignorer.js | `src/cli/directory-ignorer.js` | ソース | デフォルト無視パターンの定義 |
