# 帳票設計書 3-ファイル情報

## 概要

本ドキュメントは、指定ファイルのパーサー情報等をJSON形式で出力する帳票「ファイル情報」の設計仕様を定義する。

### 本帳票の処理概要

**業務上の目的・背景**：Prettierを他のツールと統合する際、特定のファイルに対してどのパーサーが使用されるか、そのファイルが無視対象かどうかを事前に確認する必要がある。本帳票は、エディタプラグインやビルドツールがPrettierのフォーマット対象を判断するための情報を提供する。これにより、ツール側でPrettierの動作を予測し、適切な処理分岐を行うことが可能となる。

**帳票の利用シーン**：エディタプラグインでのファイル判定、ビルドツールでのフォーマット対象選定、CI/CDパイプラインでの事前チェック、プロジェクト設定の検証など。

**主要な出力内容**：
1. ファイルが無視対象かどうかのフラグ（ignored）
2. 推論されたパーサー名（inferredParser）

**帳票の出力タイミング**：CLIで`--file-info <path>`オプションを指定した際、またはAPI経由で`getFileInfo(file, options)`関数を呼び出した際に出力される。

**帳票の利用者**：エディタプラグイン開発者、ビルドツール開発者、CI/CDエンジニア

## 帳票種別

情報出力（JSON）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| CLI-01 | コマンドライン | `prettier --file-info <path>` | コマンド実行 |
| API-01 | JavaScript API | `prettier.getFileInfo(file, options)` | 関数呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON |
| 出力先 | 標準出力 |
| 文字コード | UTF-8 |
| フォーマット | 整形済みJSON（Prettierでフォーマット） |

### JSON構造

```json
{
  "ignored": false,
  "inferredParser": "babel"
}
```

## 帳票レイアウト

### レイアウト概要

出力は2つの主要プロパティで構成されるシンプルなJSONオブジェクト。

```
┌─────────────────────────────────────┐
│              JSONオブジェクト          │
├─────────────────────────────────────┤
│  {                                   │
│    "ignored": boolean,               │
│    "inferredParser": string | null   │
│  }                                   │
└─────────────────────────────────────┘
```

### 出力項目

| No | 項目名 | 説明 | 型 | 備考 |
|----|-------|------|-----|------|
| 1 | ignored | 無視対象フラグ | boolean | .prettierignore等でマッチした場合true |
| 2 | inferredParser | 推論パーサー名 | string \| null | 特定できない場合null |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| file | 対象ファイルパス | Yes |
| ignorePath | 無視ファイルパス | No |
| withNodeModules | node_modules含む | No（デフォルト: false） |
| plugins | 追加プラグイン | No |
| resolveConfig | 設定ファイル参照 | No（デフォルト: true） |

### 判定ロジック

| 判定項目 | 条件 | 結果 |
|---------|------|------|
| ignored | ignorePath指定のファイルにマッチ | true |
| ignored | node_modules内 & withNodeModules=false | true |
| inferredParser | ファイル拡張子・名前から推論 | パーサー名 |
| inferredParser | 設定ファイルで指定 | 設定値優先 |
| inferredParser | 特定不可 | null |

## データフロー仕様

### 入力データ

| データ項目 | 型 | 説明 |
|-----------|-----|------|
| file | string \| URL | 対象ファイルパス |
| options.ignorePath | string \| string[] | 無視ファイルパス |
| options.withNodeModules | boolean | node_modules含むフラグ |
| options.plugins | array | 追加プラグイン |
| options.resolveConfig | boolean | 設定ファイル参照フラグ |

### 出力データ

| データ項目 | 型 | 説明 |
|-----------|-----|------|
| ignored | boolean | 無視対象フラグ |
| inferredParser | string \| null | 推論パーサー名 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[--file-info実行] --> B[logFileInfoOrDie呼び出し]
    B --> C[path.resolve]
    C --> D[getFileInfo呼び出し]
    D --> E{ignored判定}
    E -->|Yes| F[ignored: true返却]
    E -->|No| G[パーサー推論]
    G --> H{設定ファイル参照?}
    H -->|Yes| I[resolveConfig]
    H -->|No| J[inferParser]
    I --> K{設定にparser?}
    K -->|Yes| L[設定値使用]
    K -->|No| J
    J --> M[結果返却]
    L --> M
    F --> N[JSON文字列化]
    M --> N
    N --> O[Prettierでフォーマット]
    O --> P[標準出力]
```

### パーサー推論フロー

```mermaid
flowchart TD
    A[inferParser] --> B{設定にparser?}
    B -->|Yes| C[設定値返却]
    B -->|No| D[プラグイン読み込み]
    D --> E[拡張子からパーサー特定]
    E --> F{特定成功?}
    F -->|Yes| G[パーサー名返却]
    F -->|No| H[ファイル名から特定]
    H --> I{特定成功?}
    I -->|Yes| J[パーサー名返却]
    I -->|No| K[null返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 型エラー | fileが文字列/URLでない | expect `file` to be a string or URL | ファイルパスを正しく指定 |
| 複数ファイル指定 | --file-infoと複数ファイル | Cannot use --file-info with multiple files | 単一ファイルを指定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 処理方式 | 非同期処理（async/await） |
| 設定キャッシュ | resolveConfigの結果をキャッシュ可能 |
| 処理時間 | 数ms〜数十ms |

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

- ファイルの内容は読み込まず、パスと拡張子のみで判定
- ignorePath指定時は指定ファイルの内容を読み込む

## 備考

- --config-precedenceオプションとは併用できない
- API使用時はignorePathに単一パスも指定可能（内部で配列に変換）
- 出力は`fast-json-stable-stringify`で安定した順序を保証

---

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

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

### 推奨読解順序

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

まず、ファイル情報の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | get-file-info.js | `src/common/get-file-info.js` | FileInfoResult型定義（7-8行目） |

**読解のコツ**: 戻り値は`{ ignored: boolean, inferredParser: string | null }`のシンプルな構造。

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

CLIからの処理起点を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/cli/index.js` | context.argv.fileInfo判定（92-95行目） |
| 2-2 | file-info.js | `src/cli/file-info.js` | logFileInfoOrDie関数全体（7-26行目） |

**主要処理フロー**:
1. **92-95行目**: fileInfoオプションの判定とlogFileInfoOrDie呼び出し
2. **16行目**: getFileInfoで情報取得
3. **23行目**: Prettierでフォーマット
4. **25行目**: 標準出力へ出力

#### Step 3: ファイル情報取得処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | get-file-info.js | `src/common/get-file-info.js` | getFileInfo関数（19-42行目） |
| 3-2 | get-file-info.js | `src/common/get-file-info.js` | getParser関数（44-67行目） |

**主要処理フロー**:
- **20-24行目**: 入力型チェック
- **26-30行目**: ignorePath配列化
- **32行目**: isIgnored判定
- **35行目**: パーサー推論

#### Step 4: 無視判定処理を理解する

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

**主要処理フロー**:
- ignorePathで指定されたファイルを読み込み
- globパターンでマッチング判定

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

```
CLI: main() [src/cli/index.js:39]
    │
    └─ logFileInfoOrDie() [src/cli/file-info.js:7]
           │
           ├─ path.resolve() [node:path]
           │
           ├─ getFileInfo() [src/common/get-file-info.js:19]
           │      │
           │      ├─ isIgnored() [src/utilities/ignore.js]
           │      │
           │      └─ getParser() [src/common/get-file-info.js:44]
           │             │
           │             ├─ resolveConfig() [src/config/resolve-config.js]
           │             │
           │             ├─ loadBuiltinPlugins() [src/main/plugins/index.js]
           │             │
           │             ├─ loadPlugins() [src/main/plugins/index.js]
           │             │
           │             └─ inferParser() [src/utilities/infer-parser.js]
           │
           ├─ stringify() [fast-json-stable-stringify]
           │
           ├─ format() [src/index.js:68]
           │
           └─ printToScreen() [src/cli/utilities.js:8]
```

### データフロー図

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

ファイルパス ──────────▶ path.resolve() ──────────▶ 絶対パス
                              │
                              ▼
                         isIgnored()
                              │
                              ▼
                    ignored判定結果 (boolean)
                              │
                              │ (ignored=false時のみ)
                              ▼
                         getParser()
                              │
                              ▼
                    inferredParser (string|null)
                              │
                              ▼
                     stringify() + format()
                              │
                              ▼
{ ignored, inferredParser } ◀──────────────────▶ 整形済みJSON出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| file-info.js | `src/cli/file-info.js` | ソース | CLI用ファイル情報出力 |
| get-file-info.js | `src/common/get-file-info.js` | ソース | ファイル情報取得ロジック |
| index.js | `src/index.js` | ソース | getFileInfo API公開 |
| ignore.js | `src/utilities/ignore.js` | ソース | 無視判定ロジック |
| infer-parser.js | `src/utilities/infer-parser.js` | ソース | パーサー推論ロジック |
| resolve-config.js | `src/config/resolve-config.js` | ソース | 設定ファイル解決 |
| utilities.js | `src/cli/utilities.js` | ソース | printToScreen関数 |
