# 機能設計書 59-Pragma必須（requirePragma）

## 概要

本ドキュメントは、Prettierの`requirePragma`オプションに関する機能設計書である。このオプションは、ファイルの先頭に特別なコメント（Pragma）が含まれている場合のみフォーマットを実行するよう制限する。大規模なコードベースへのPrettier導入を段階的に行う場合に有用である。

### 本機能の処理概要

**業務上の目的・背景**：大規模なレガシーコードベースにPrettierを一度に適用すると、膨大な差分が発生し、コードレビューやgit blameが困難になる。`requirePragma`を使用すると、明示的にマークされたファイルのみをフォーマットでき、段階的な導入が可能になる。新規ファイルや修正したファイルにのみPragmaを追加することで、徐々にフォーマット済みファイルを増やせる。

**機能の利用シーン**：大規模プロジェクトへのPrettier段階導入、レガシーコードの保護、特定ファイルのみフォーマットしたい場合に使用される。

**主要な処理内容**：
1. オプション値（true/false）の読み込み
2. trueの場合、ファイル先頭のDocblockコメントを解析
3. `@prettier`または`@format`プラグマの存在を確認
4. プラグマがない場合、フォーマットをスキップして元のテキストを返却

**関連システム・外部連携**：すべての言語パーサーのhasPragma関数と連携して動作する。

**権限による制御**：権限による制御は存在しない。設定ファイルまたはCLIオプションで指定する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Playground | 補助機能 | サイドバーからPragma必須オプションを設定 |
| 19 | Configuration - Options | 主機能 | requirePragmaオプションの詳細説明 |

## 機能種別

設定オプション / フォーマット制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| requirePragma | boolean | No | Pragmaを必須とするかどうか | true/falseのブール値のみ許可 |

### 入力データソース

- 設定ファイル（.prettierrc、prettier.config.js等）
- CLIオプション（--require-pragma）
- プログラマティックAPI呼び出し時のオプションオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| formattedCode | string | Pragma判定が適用されたフォーマット結果（またはオリジナル） |

### 出力先

フォーマット結果は呼び出し元に返却される（標準出力、ファイル、API戻り値）。

## 処理フロー

### 処理シーケンス

```
1. オプション解析
   └─ requirePragmaオプションの値を取得（デフォルト: false）
2. Pragma不要の場合
   └─ 通常のフォーマット処理を実行
3. Pragma必須の場合
   └─ hasPragma関数でPragmaの存在を確認
4. Pragma判定
   └─ @prettierまたは@formatがあればフォーマット実行
5. Pragmaなし
   └─ 元のテキストをそのまま返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{requirePragma?}
    B -->|false| C[通常フォーマット]
    B -->|true| D[hasPragma実行]
    D --> E{Pragmaあり?}
    E -->|Yes| C
    E -->|No| F[元のテキストを返却]
    C --> G[フォーマット済みテキスト]
    F --> G
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-59-1 | デフォルト動作 | Pragmaなしでもフォーマットを実行 | requirePragma = false（デフォルト） |
| BR-59-2 | Pragma必須 | Pragmaがあるファイルのみフォーマット | requirePragma = true |
| BR-59-3 | 認識Pragma | @prettierまたは@formatを認識 | 常時 |
| BR-59-4 | Docblockコメント | ファイル先頭のDocblock（/** */）内をチェック | JavaScript等 |
| BR-59-5 | 言語依存 | 各言語のhasPragma実装に依存 | 常時 |

### 計算ロジック

```javascript
// Pragma判定ロジック（core.js）
if (options.requirePragma && !(await hasPragma(text, options))) {
  return {
    formatted: originalText,
    cursorOffset: originalOptions.cursorOffset,
    comments: [],
  };
}
```

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

データベース操作は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型エラー | boolean以外の値が指定された場合 | Prettierのオプション検証でエラーが発生 |

### リトライ仕様

リトライは不要（同期的な設定適用処理）。

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

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

## パフォーマンス要件

Docblockの解析は軽量であり、パフォーマンスへの影響は軽微。

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

セキュリティに関する特別な考慮事項は存在しない。

## 備考

- `insertPragma`オプションと組み合わせることで、フォーマット済みファイルにPragmaを自動挿入できる。
- 言語ごとにhasPragma関数の実装が異なる場合がある。
- jest-docblockライブラリを使用してDocblockを解析する（JavaScript）。

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: このファイルでは、requirePragmaがboolean型でデフォルトfalse、Specialカテゴリ（CLI表示ではOther）に属することを確認する。

#### Step 2: コア処理での使用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | core.js | `src/main/core.js` | formatWithCursor関数でのrequirePragma使用 |

**主要処理フロー**:
1. **332行目**: `options.requirePragma && !(await hasPragma(text, options))`の条件チェック
2. **314-317行目**: hasPragma関数の定義
3. **335-339行目**: Pragmaがない場合の早期リターン

#### Step 3: JavaScript固有のPragma処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | pragma.js | `src/language-js/pragma.js` | JavaScriptのhasPragma実装 |

**主要処理フロー**:
- **1行目**: jest-docblockからextract、parseWithComments等をインポート
- **10-19行目**: parseDocBlock関数でDocblockを解析
- **22-25行目**: hasPragma関数の実装
- **6-7行目**: FORMAT_PRAGMAS（@prettier、@format）の参照

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

```
formatWithCursor (core.js)
    │
    ├─ options.requirePragma チェック (332行目)
    │
    └─ hasPragma (core.js:314)
           │
           └─ resolveParser (parser-and-printer.js)
                  │
                  └─ selectedParser.hasPragma (言語固有)
                         │
                         └─ JavaScript: pragma.js:22
                               ├─ parseDocBlock
                               │      ├─ getShebang
                               │      └─ jest-docblock.extract
                               └─ FORMAT_PRAGMAS.some(...)
```

### データフロー図

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

オプション設定 ───▶ formatWithCursor関数 ───▶ フォーマット結果
(requirePragma)        (core.js)
        │
        ▼
ソースコード ───▶ hasPragma判定 ───▶ true: フォーマット実行
                     │              false: 元のテキスト返却
                     ▼
                parseDocBlock
                     │
                     ▼
                @prettier/@format検出
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| core-options.evaluate.js | `src/main/core-options.evaluate.js` | ソース | オプション定義（183-190行目） |
| core.js | `src/main/core.js` | ソース | requirePragma使用箇所（332, 348行目） |
| pragma.js | `src/language-js/pragma.js` | ソース | JavaScriptのPragma処理 |
| pragma.evaluate.js | `src/utilities/pragma/pragma.evaluate.js` | ソース | FORMAT_PRAGMASの定義 |
| pragma.js | `src/language-css/pragma.js` | ソース | CSSのPragma処理 |
| pragma.js | `src/language-graphql/pragma.js` | ソース | GraphQLのPragma処理 |
| pragma.js | `src/language-markdown/pragma.js` | ソース | MarkdownのPragma処理 |
| pragma.js | `src/language-yaml/pragma.js` | ソース | YAMLのPragma処理 |
| pragma.js | `src/language-html/pragma.js` | ソース | HTMLのPragma処理 |
| index.d.ts | `src/index.d.ts` | 型定義 | TypeScript型定義（379行目） |
