# 機能設計書 27-ファイル情報取得（getFileInfo）

## 概要

本ドキュメントは、Prettier APIにおける`getFileInfo`関数の機能設計を記述する。この関数は、指定されたファイルが無視対象かどうかと、推論されたパーサー名を取得する。

### 本機能の処理概要

**業務上の目的・背景**：エディタ統合やビルドツールがPrettierを使用する際、ファイルがフォーマット対象かどうか、どのパーサーを使用すべきかを事前に知る必要がある。本機能は、この情報をプログラマティックに取得するAPIを提供する。CLIの`--file-info`オプションはこの関数のラッパーである。

**機能の利用シーン**：
- エディタプラグインでのファイル判定
- ビルドツールでのパーサー選択
- カスタムスクリプトでのファイルフィルタリング
- フォーマット前の事前チェック

**主要な処理内容**：
1. 入力ファイルパスのバリデーション
2. ignoreファイルに基づく無視状態の判定
3. ファイル拡張子・設定ファイル・インタープリタからのパーサー推論
4. 結果オブジェクトの構築

**関連システム・外部連携**：
- ignoreファイル処理
- 設定ファイル解決（resolveConfig）
- プラグインシステム

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 16 | Usage - API | 補助機能 | APIでのgetFileInfo関数の使い方を説明 |

## 機能種別

情報取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| file | string \| URL | Yes | 情報を取得するファイルパス | 文字列またはURLオブジェクト |
| options | FileInfoOptions | No | オプション | オブジェクト |
| options.ignorePath | string \| URL \| (string \| URL)[] | No | ignoreファイルのパス | 単一または配列 |
| options.withNodeModules | boolean | No | node_modulesを処理対象に含める | デフォルト: false |
| options.plugins | string[] | No | 使用するプラグインのパス | パスの配列 |
| options.resolveConfig | boolean | No | 設定ファイルを解決するか | デフォルト: true |
| options.parser | string | No | 明示的にパーサーを指定 | パーサー名 |

### 入力データソース

- 関数引数
- ファイルシステム（ignoreファイル、設定ファイル）
- プラグイン

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ignored | boolean | ファイルが無視対象かどうか |
| inferredParser | string \| null | 推論されたパーサー名（推論できない場合はnull） |

### 出力先

- 戻り値（Promise<FileInfoResult>）

**使用例**：
```javascript
import { getFileInfo } from "prettier";

const info = await getFileInfo("./src/index.js");
console.log(info);
// { ignored: false, inferredParser: "babel" }
```

## 処理フロー

### 処理シーケンス

```
1. 入力バリデーション
   └─ fileが文字列またはURLオブジェクトか確認
   └─ 不正な場合はTypeErrorをスロー

2. ignorePathの正規化
   └─ 単一値の場合は配列に変換

3. ignored判定
   └─ isIgnored関数を呼び出し

4. パーサー推論（ignoredがfalseの場合のみ）
   └─ options.parserが指定されていればそれを使用
   └─ そうでなければgetParser関数で推論

5. 結果構築
   └─ { ignored, inferredParser }オブジェクトを返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{fileの型チェック}
    B -->|不正| C[TypeError]
    B -->|正常| D[ignorePathを配列化]
    D --> E[isIgnored判定]
    E --> F{ignored?}
    F -->|Yes| G[inferredParser未設定]
    F -->|No| H{options.parser指定?}
    H -->|Yes| I[options.parserを使用]
    H -->|No| J[getParser呼び出し]
    J --> K{resolveConfig?}
    K -->|Yes| L[設定ファイル解決]
    K -->|No| M[プラグインのみで推論]
    L --> N[パーサー推論]
    M --> N
    I --> O[結果構築]
    G --> O
    N --> O
    O --> P[Promise<FileInfoResult>]
    P --> Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-27-1 | 型チェック | fileは文字列またはURLでなければTypeError | 常時 |
| BR-27-2 | 無視優先 | ignoredがtrueの場合、inferredParserは計算されない | ignored時 |
| BR-27-3 | 設定ファイル連携 | resolveConfigがtrueの場合、設定のparserを優先 | resolveConfig時 |
| BR-27-4 | 明示的パーサー | options.parserが指定された場合、推論より優先 | parser指定時 |
| BR-27-5 | プラグイン必須 | パーサー推論にはプラグイン（ビルトインまたは外部）が必要 | パーサー推論時 |

### 計算ロジック

**パーサー推論の優先順位**：
1. `options.parser`（明示的指定）
2. 設定ファイルの`parser`オプション（resolveConfig時）
3. ファイル名/拡張子からの推論
4. インタープリタからの推論（shebang行）

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | TypeError | fileが文字列でもURLでもない | 適切な型の引数を渡す |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

- 設定ファイル解決を含む場合は若干の遅延がありうる
- プラグイン読み込みが必要な場合は初回に時間がかかる

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

- ファイルパスとパーサー名のみを返す
- 機密情報の漏洩リスクは低い

## 備考

- CLIの`--file-info`オプションはこの関数を内部で使用
- VSCode拡張などのエディタ統合で広く使用されている

---

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

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

### 推奨読解順序

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

FileInfoOptionsとFileInfoResultの型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | get-file-info.js | `src/common/get-file-info.js` | @typedefコメントで定義されている型 |

**読解のコツ**: JSDocの`@typedef`で型が定義されている。`FileInfoOptions`と`FileInfoResult`の構造を確認する。

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

getFileInfo関数の実装を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | get-file-info.js | `src/common/get-file-info.js` | getFileInfo関数の全体構造 |
| 2-2 | index.js | `src/index.js` | getFileInfoのエクスポート |

**主要処理フロー**:
- **19-24行目**: 入力バリデーション
- **26-29行目**: ignorePathの配列化
- **32行目**: isIgnored判定
- **34-36行目**: 無視されていない場合のみパーサー推論
- **38-41行目**: 結果オブジェクト構築

#### Step 3: パーサー推論ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | get-file-info.js | `src/common/get-file-info.js` | getParser関数 |
| 3-2 | infer-parser.js | `src/utilities/infer-parser.js` | inferParser関数 |

**主要処理フロー（get-file-info.js::getParser）**:
- **44-51行目**: resolveConfigオプションに基づく設定解決
- **53-55行目**: 設定のparserがあればそれを返す
- **57-64行目**: プラグイン読み込み
- **66行目**: inferParser呼び出し

**主要処理フロー（infer-parser.js::inferParser）**:
- **115-133行目**: 言語マッチングの優先順位
  - 言語名
  - ファイル名（physicalFile）
  - ファイル名（file）
  - isSupported
  - インタープリタ

#### Step 4: ignore判定を理解する

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

**主要処理フロー**:
- **83-87行目**: isIgnored関数（createIsIgnoredFunctionのラッパー）

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

```
src/common/get-file-info.js::getFileInfo()
    │
    ├─ 入力バリデーション
    │
    ├─ src/utilities/ignore.js::isIgnored()
    │      │
    │      └─ createIsIgnoredFunction()
    │
    └─ getParser() [ignoredがfalseの場合]
           │
           ├─ src/config/resolve-config.js::resolveConfig()
           │
           ├─ src/main/plugins/index.js::loadBuiltinPlugins()
           │
           ├─ src/main/plugins/index.js::loadPlugins()
           │
           └─ src/utilities/infer-parser.js::inferParser()
                  ├─ getLanguageByLanguageName()
                  ├─ getLanguageByFileName()
                  ├─ getLanguageByIsSupported()
                  └─ getLanguageByInterpreter()
```

### データフロー図

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

file (string | URL) ────▶ 入力バリデーション ────────────▶ TypeError or 続行
                               │
                               ▼
options.ignorePath ─────▶ 配列化 ──────────────────────▶ ignorePathArray
                               │
                               ▼
ignoreファイル ──────────▶ isIgnored() ─────────────────▶ ignored: boolean
                               │
                               ▼
options.parser ──────────▶ パーサー決定 ─────────────────▶ (明示的指定)
または                         │
設定ファイル ─────────────▶│
プラグイン ───────────────▶│
ファイル拡張子 ───────────▶ inferParser() ───────────────▶ inferredParser: string|null
                               │
                               ▼
                         結果構築 ─────────────────────▶ { ignored, inferredParser }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| get-file-info.js | `src/common/get-file-info.js` | ソース | メイン実装 |
| index.js | `src/index.js` | ソース | API公開エントリーポイント |
| ignore.js | `src/utilities/ignore.js` | ソース | ignore判定 |
| infer-parser.js | `src/utilities/infer-parser.js` | ソース | パーサー推論 |
| resolve-config.js | `src/config/resolve-config.js` | ソース | 設定ファイル解決 |
| load-plugins.js | `src/main/plugins/load-plugins.js` | ソース | プラグイン読み込み |
