# 機能設計書 22-Ignoreファイル処理（--ignore-path）

## 概要

本ドキュメントは、Prettier CLIにおける`--ignore-path`オプションの機能設計を記述する。このオプションは、.gitignoreや.prettierignoreファイルに基づいてフォーマット対象から除外するファイルを指定する。

### 本機能の処理概要

**業務上の目的・背景**：プロジェクトには、フォーマットすべきでないファイルが含まれることがある。ビルド成果物、サードパーティライブラリ、自動生成ファイルなどは、Prettierでフォーマットする必要がない。本機能は、こうしたファイルを効率的に除外し、必要なファイルのみをフォーマット対象とする。

**機能の利用シーン**：
- node_modulesディレクトリの除外（デフォルト動作）
- ビルド成果物（dist/, build/等）の除外
- vendorディレクトリやサードパーティコードの除外
- 自動生成ファイルの除外

**主要な処理内容**：
1. ignoreファイルパスの解決（デフォルト: .gitignore, .prettierignore）
2. ignoreファイルの読み込みと解析
3. ignoreパターンのコンパイル
4. 各ファイルパスに対するマッチング判定
5. マッチしたファイルの除外

**関連システム・外部連携**：
- `ignore`パッケージによるgitignore形式パターンマッチング
- ファイルシステムからのignoreファイル読み込み

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | Usage - Ignore | 主機能 | .prettierignoreの設定方法と無視ルールを説明 |
| 15 | Usage - CLI | 補助機能 | CLIでの無視パス指定を説明 |

## 機能種別

バリデーション / ファイルフィルタリング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --ignore-path | path[] | No | ignoreファイルのパス（複数指定可） | デフォルト: [".gitignore", ".prettierignore"] |
| --with-node-modules | boolean | No | node_modulesを処理対象に含める | デフォルト: false |

### 入力データソース

- CLIコマンドライン引数
- ignoreファイル（.gitignore、.prettierignore等）
- ファイルシステム

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| isIgnored | function | ファイルパスが無視対象かを判定する関数 |

### 出力先

- 内部処理（フォーマット対象ファイルのフィルタリング）

## 処理フロー

### 処理シーケンス

```
1. ignoreファイルパスの解決
   └─ デフォルト値または--ignore-path指定値を使用

2. ignoreファイルの読み込み
   └─ 各ignoreファイルを非同期で読み込み
   └─ ファイルが存在しない場合は空文字列として処理

3. ignoreパターンの構築
   └─ ignoreパッケージでパターンをコンパイル
   └─ --with-node-modulesがfalseの場合、"node_modules"パターンを追加

4. isIgnored関数の生成
   └─ ファイルパスを相対パスに変換
   └─ 複数のignoreファイルに対してOR条件でマッチング

5. ファイルフィルタリング
   └─ 各対象ファイルに対してisIgnored関数を適用
   └─ trueを返すファイルをスキップ
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ignoreパス解決]
    B --> C[ignoreファイル読み込み]
    C --> D{ファイル存在?}
    D -->|Yes| E[パターン解析]
    D -->|No| F[空パターン]
    E --> G[ignoreインスタンス作成]
    F --> G
    G --> H{--with-node-modules?}
    H -->|No| I[node_modulesパターン追加]
    H -->|Yes| J[isIgnored関数生成]
    I --> J
    J --> K[対象ファイルに適用]
    K --> L{マッチ?}
    L -->|Yes| M[ファイルスキップ]
    L -->|No| N[フォーマット対象]
    M --> O{次のファイル?}
    N --> O
    O -->|Yes| K
    O -->|No| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-22-1 | デフォルトignoreファイル | .gitignoreと.prettierignoreがデフォルトで使用される | --ignore-path未指定時 |
| BR-22-2 | 複数ignoreファイル | 複数のignoreファイルを指定可能（OR条件） | --ignore-path複数指定時 |
| BR-22-3 | node_modules除外 | デフォルトでnode_modulesは除外される | --with-node-modules未指定時 |
| BR-22-4 | 相対パス変換 | ファイルパスはignoreファイルからの相対パスに変換 | パターンマッチング時 |
| BR-22-5 | パス区切り文字 | Windowsのバックスラッシュはスラッシュに変換 | パターンマッチング時 |

### 計算ロジック

**相対パス計算**：
```javascript
relativePath = path.relative(
  ignoreFilePath ? path.dirname(ignoreFilePath) : process.cwd(),
  filePath
);
```

**マッチング判定**：
```javascript
isIgnored = ignoreInstance.checkIgnore(slash(relativePath)).ignored;
```

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | FileReadError | ignoreファイル読み込み失敗 | エラーメッセージ表示、終了コード2 |

### リトライ仕様

リトライは行わない。

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

トランザクション管理は不要。

## パフォーマンス要件

- ignoreパターンは一度コンパイルされ、全ファイルに対して再利用される
- 大量のファイルがある場合でも、パターンマッチングは高速に行われる

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

- ignoreファイルの内容はフィルタリング目的のみに使用
- 機密情報を含むパスが漏洩するリスクはない

## 備考

- gitignore形式のパターン構文をサポート
- `!`プレフィックスによる否定パターンもサポート

---

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

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

### 推奨読解順序

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

ignoreパターンの処理に使用されるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ignore.js | `src/utilities/ignore.js` | isIgnored関数とcreateIsIgnoredFunction関数の構造 |

**読解のコツ**: `ignore`パッケージの`createIgnore`関数がgitignore形式のパターンをコンパイルする。

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

CLIオプションの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ignorePathとwithNodeModulesオプションの定義 |

**主要処理フロー**:
- **195-204行目**: ignorePathオプション定義（array: true、デフォルト値）
- **232-236行目**: withNodeModulesオプション定義

#### Step 3: ignore処理の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ignore.js | `src/utilities/ignore.js` | createSingleIsIgnoredFunction関数の実装 |

**主要処理フロー**:
- **35-54行目**: 単一ignoreファイルからのisIgnored関数生成
- **42-44行目**: node_modulesパターンの追加
- **50行目**: ignoreインスタンス生成（allowRelativePaths: true）
- **52-53行目**: checkIgnoreによるマッチング判定

#### Step 4: 複数ignoreファイルの統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ignore.js | `src/utilities/ignore.js` | createIsIgnoredFunction関数の実装 |

**主要処理フロー**:
- **61-76行目**: 複数ignoreファイルの処理
- **63-65行目**: 空配列の場合の処理
- **75行目**: OR条件でのマッチング（someを使用）

#### Step 5: CLI/APIでの使用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | format.js | `src/cli/format.js` | formatFiles関数でのisIgnored使用 |
| 5-2 | get-file-info.js | `src/common/get-file-info.js` | API経由でのisIgnored使用 |

**主要処理フロー（format.js）**:
- **213-223行目**: createIsIgnoredFromContextOrDie関数
- **275行目**: isIgnored関数の取得
- **315-324行目**: ファイルのスキップ判定

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

```
src/cli/format.js::formatFiles()
    │
    ├─ src/cli/format.js::createIsIgnoredFromContextOrDie()
    │      │
    │      └─ src/utilities/ignore.js::createIsIgnoredFunction()
    │             │
    │             ├─ createSingleIsIgnoredFunction()
    │             │      ├─ readFile() - ignoreファイル読み込み
    │             │      └─ createIgnore() - パターンコンパイル
    │             │
    │             └─ isIgnoredFunctions.some() - OR条件マッチング
    │
    └─ isIgnored(filename) - 各ファイルの判定
```

### データフロー図

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

--ignore-path ────────────▶ パス解決 ─────────────────────▶ ignoreファイルパス
                                │
                                ▼
ignoreファイル ───────────▶ ファイル読み込み ───────────▶ パターン文字列
                                │
                                ▼
--with-node-modules ──────▶ パターン構築 ─────────────────▶ ignoreインスタンス
                                │
                                ▼
対象ファイルパス ──────────▶ マッチング判定 ──────────────▶ true/false (ignored)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ignore.js | `src/utilities/ignore.js` | ソース | ignore処理の中核実装 |
| cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ソース | CLIオプション定義 |
| format.js | `src/cli/format.js` | ソース | フォーマット処理でのignore使用 |
| get-file-info.js | `src/common/get-file-info.js` | ソース | API経由でのignore使用 |
| directory-ignorer.js | `src/cli/directory-ignorer.js` | ソース | ディレクトリレベルでの除外 |
| read-file.js | `src/utilities/read-file.js` | ソース | ファイル読み込みユーティリティ |
