# 機能設計書 61-Ignore Pragmaチェック（checkIgnorePragma）

## 概要

本ドキュメントは、Prettierのコードフォーマッタにおける「Ignore Pragmaチェック」機能の設計を記述する。この機能は、ファイルの先頭コメントに含まれる特定のプラグマ（@noprettierまたは@noformat）を検出し、該当ファイルをフォーマット対象から除外する機能である。

### 本機能の処理概要

**業務上の目的・背景**：大規模なコードベースでは、意図的にフォーマットを適用したくないファイルが存在する場合がある。例えば、生成されたコード、特定のレイアウトを維持したいファイル、または外部ライブラリからコピーしたコードなどである。checkIgnorePragma機能は、これらのファイルに対して個別に除外設定を行わなくても、ファイル自身にプラグマを記述することでフォーマットを回避できるようにする。これにより、.prettierignoreファイルの管理負担を軽減し、ファイル単位での柔軟なフォーマット制御を実現する。

**機能の利用シーン**：
- 生成されたコードファイルをフォーマットから除外したい場合
- 特定のコードレイアウトを維持したい場合（例：ASCIIアートを含むコメント）
- 外部ライブラリからコピーしたコードをオリジナルのまま保持したい場合
- チーム内で特定のファイルをフォーマット対象外にする合意がある場合

**主要な処理内容**：
1. オプション「checkIgnorePragma」がtrueに設定されているかを確認する
2. ファイルの先頭にあるdocblockコメントを解析する
3. docblock内に「@noprettier」または「@noformat」が含まれているかを検出する
4. プラグマが検出された場合、フォーマット処理をスキップし元のテキストをそのまま返却する

**関連システム・外部連携**：
- パーサーシステム: 各言語パーサーにhasIgnorePragma関数が実装されている必要がある
- 設定システム: core-options.evaluate.jsでオプションが定義される

**権限による制御**：特になし（すべてのユーザーが利用可能）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | Configuration - Options | 主機能 | checkIgnorePragmaオプションの詳細説明 |

## 機能種別

バリデーション / 条件分岐処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| checkIgnorePragma | boolean | No | Ignore Pragmaチェックを有効化するかどうか | デフォルト: false |
| text | string | Yes | フォーマット対象のソースコード | 空文字列も許容 |
| options | object | Yes | フォーマットオプション | parserが必須 |

### 入力データソース

- APIを通じて渡されるフォーマット対象テキスト
- CLIオプション「--check-ignore-pragma」
- 設定ファイル（.prettierrc等）の「checkIgnorePragma」設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| formatted | string | フォーマット後のテキスト（プラグマ検出時は元テキスト） |
| cursorOffset | number | カーソル位置（プラグマ検出時は元の位置） |
| comments | array | コメント配列（プラグマ検出時は空配列） |

### 出力先

- APIの戻り値として呼び出し元に返却
- CLIでは標準出力またはファイル書き込み

## 処理フロー

### 処理シーケンス

```
1. formatWithCursor関数が呼び出される
   └─ オプションの正規化（normalizeFormatOptions）を実行
2. checkIgnorePragmaオプションの確認
   └─ オプションがfalseの場合はスキップ
3. hasIgnorePragma関数の呼び出し
   └─ パーサーからhasIgnorePragma関数を取得
4. プラグマの検出
   └─ ファイル先頭のdocblockを解析
5. 結果に基づく分岐
   └─ プラグマあり: 元テキストをそのまま返却
   └─ プラグマなし: 通常のフォーマット処理を継続
```

### フローチャート

```mermaid
flowchart TD
    A[開始: formatWithCursor] --> B{checkIgnorePragma == true?}
    B -->|No| C[通常フォーマット処理へ]
    B -->|Yes| D[hasIgnorePragma呼び出し]
    D --> E{プラグマ検出?}
    E -->|No| C
    E -->|Yes| F[元テキストをそのまま返却]
    F --> G[終了]
    C --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-61-01 | プラグマ検出条件 | @noprettierまたは@noformatがdocblockに存在する | checkIgnorePragma=true |
| BR-61-02 | 優先順位 | checkIgnorePragmaはrequirePragmaより後に評価される | 両オプションがtrueの場合 |
| BR-61-03 | パーサー依存 | hasIgnorePragma関数はパーサーごとに実装される | パーサーによって挙動が異なる可能性 |

### 計算ロジック

特になし（検出はパーサーに委譲）

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

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

本機能はデータベース操作を伴わない。

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パーサーエラー | パーサーにhasIgnorePragma関数が未実装 | 関数が存在しない場合はundefinedを返しfalseとして扱う |

### リトライ仕様

リトライは不要（パーサーエラーは即座に判定可能）

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

該当なし（データベース操作なし）

## パフォーマンス要件

- プラグマチェックは高速に完了すること（ファイル先頭のみを解析）
- 大量のファイル処理時もオーバーヘッドが最小限であること

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

- 特別なセキュリティ要件なし
- プラグマはファイル内容の一部として扱われ、外部入力による影響なし

## 備考

- この機能はrequirePragma（No.59）と対になる機能である
- requirePragmaがフォーマット対象を絞り込むのに対し、checkIgnorePragmaはフォーマット対象から除外する

---

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

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

### 推奨読解順序

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

オプション定義の構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | core-options.evaluate.js | `src/main/core-options.evaluate.js` | checkIgnorePragmaオプションの定義を確認 |

**読解のコツ**: オプション定義はカテゴリ別に整理されており、checkIgnorePragmaはCATEGORY_SPECIALに属する。デフォルト値がfalseであることに注目。

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

フォーマット処理の起点を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | core.js | `src/main/core.js` | formatWithCursor関数がエントリーポイント |

**主要処理フロー**:
1. **324-328行目**: normalizeInputAndOptionsでオプションを正規化
2. **330-334行目**: checkIgnorePragmaオプションのチェックとhasIgnorePragma呼び出し
3. **335-340行目**: プラグマ検出時の早期リターン

#### Step 3: ヘルパー関数を理解する

プラグマ検出のロジックを確認する。

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

**主要処理フロー**:
- **319-322行目**: hasIgnorePragma関数の定義。パーサーからhasIgnorePragma関数を取得し、存在する場合のみ呼び出す

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

```
formatWithCursor (core.js)
    │
    ├─ normalizeInputAndOptions (core.js)
    │      └─ normalizeFormatOptions (normalize-format-options.js)
    │
    ├─ hasIgnorePragma (core.js)
    │      └─ resolveParser (parser-and-printer.js)
    │             └─ selectedParser.hasIgnorePragma (各言語パーサー)
    │
    └─ [プラグマなしの場合]
           └─ coreFormat / formatRange (core.js)
```

### データフロー図

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

options                   formatWithCursor                 {formatted, cursorOffset, comments}
  │                            │                                 │
  ├── checkIgnorePragma ─────▶ checkIgnorePragma判定 ──────────▶ プラグマあり: 元テキスト返却
  │                            │
  └── text ─────────────────▶ hasIgnorePragma ─────────────────▶ プラグマなし: フォーマット継続
                               │
                               └── パーサー.hasIgnorePragma
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| core-options.evaluate.js | `src/main/core-options.evaluate.js` | ソース | オプション定義 |
| core.js | `src/main/core.js` | ソース | メインフォーマット処理、プラグマチェック |
| parser-and-printer.js | `src/main/parser-and-printer.js` | ソース | パーサー解決 |
| normalize-format-options.js | `src/main/normalize-format-options.js` | ソース | オプション正規化 |
| index.js | `src/index.js` | ソース | API公開 |
