# 機能設計書 23-ファイル情報取得（--file-info）

## 概要

本ドキュメントは、Prettier CLIにおける`--file-info`オプションの機能設計を記述する。このオプションは、指定されたファイルの無視状態と推論されたパーサーをJSON形式で出力する。

### 本機能の処理概要

**業務上の目的・背景**：エディタ統合やビルドツールがPrettierを使用する際、ファイルがフォーマット対象かどうか、どのパーサーを使用すべきかを事前に知る必要がある。本機能は、APIを使用せずにCLIからこれらの情報を取得する手段を提供する。

**機能の利用シーン**：
- エディタプラグインでのファイル判定
- CI/CDパイプラインでのファイル検証
- ビルドスクリプトでのパーサー選択
- デバッグ時のファイル状態確認

**主要な処理内容**：
1. 指定されたファイルパスの解決
2. ignoreファイルに基づく無視状態の判定
3. ファイル拡張子・内容からのパーサー推論
4. 結果のJSON形式での出力

**関連システム・外部連携**：
- APIの`getFileInfo`関数を内部で使用
- ignoreファイル処理との連携
- 設定ファイル解決との連携（パーサー推論時）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | Usage - CLI | 補助機能 | CLIでのファイル情報取得を説明 |

## 機能種別

情報取得 / 診断

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --file-info | path | Yes | 情報を取得するファイルパス | 有効なファイルパス |
| --ignore-path | path[] | No | ignoreファイルのパス | デフォルト: [".gitignore", ".prettierignore"] |
| --with-node-modules | boolean | No | node_modulesを処理対象に含める | デフォルト: false |
| --plugin | string[] | No | 使用するプラグイン | - |
| --config | path/false | No | 設定ファイルのパス | --no-configで設定解決を無効化 |

### 入力データソース

- CLIコマンドライン引数
- ファイルシステム（対象ファイル、ignoreファイル、設定ファイル）

## 出力仕様

### 出力データ

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

### 出力先

- 標準出力（JSON形式、Prettierでフォーマット済み）

**出力例**：
```json
{
  "ignored": false,
  "inferredParser": "babel"
}
```

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ --file-infoオプションからファイルパスを取得

2. オプションの検証
   └─ 複数ファイル指定時はエラー

3. ファイルパスの解決
   └─ 相対パスを絶対パスに変換

4. getFileInfo API呼び出し
   └─ ignorePath、withNodeModules、plugins、resolveConfig引数を渡す

5. 結果のフォーマット
   └─ JSON形式に変換
   └─ Prettierでフォーマット

6. 出力
   └─ 標準出力に表示
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[引数解析]
    B --> C{複数ファイル?}
    C -->|Yes| D[エラー終了]
    C -->|No| E[パス解決]
    E --> F[getFileInfo呼び出し]
    F --> G[JSON変換]
    G --> H[Prettierフォーマット]
    H --> I[標準出力]
    I --> J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-23-1 | 単一ファイル制限 | --file-infoは単一ファイルのみ指定可能 | --file-info使用時 |
| BR-23-2 | 無視ファイル優先 | ignoredがtrueの場合、inferredParserは計算されない | ignored判定時 |
| BR-23-3 | 設定ファイル連携 | resolveConfigがfalseでない場合、設定ファイルのparserも考慮 | パーサー推論時 |
| BR-23-4 | プラグイン考慮 | --pluginで指定されたプラグインの言語定義を使用 | パーサー推論時 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ArgumentError | --file-infoと追加のファイルパターンを同時指定 | エラーメッセージ表示、終了 |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

- 単一ファイルの情報取得のため、高速な応答が期待される
- 設定ファイル解決を含む場合は若干の遅延がありうる

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

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

## 備考

- API関数`getFileInfo`のCLIラッパー
- `--config-precedence`オプションとは連携しない

---

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

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

### 推奨読解順序

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

出力されるFileInfoResultの構造を理解する。

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

**読解のコツ**: JSDocコメントで`@typedef`として型が定義されている。

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

CLIオプションの定義とメイン処理の流れを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | fileInfoオプションの定義 |
| 2-2 | index.js | `src/cli/index.js` | --file-infoの処理分岐 |

**主要処理フロー**:
- **172-179行目（cli-options）**: fileInfoオプション定義
- **61-63行目（index.js）**: 複数ファイル指定の検証
- **92-94行目（index.js）**: logFileInfoOrDie呼び出し

#### Step 3: CLI実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | file-info.js | `src/cli/file-info.js` | logFileInfoOrDie関数の実装 |

**主要処理フロー**:
- **7-14行目**: context.argvからオプション取得
- **16-21行目**: getFileInfo API呼び出し
- **23-25行目**: JSON出力のフォーマットと表示

#### Step 4: API実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | get-file-info.js | `src/common/get-file-info.js` | getFileInfo関数の実装 |

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

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

```
src/cli/index.js::main()
    │
    ├─ --file-info検出
    │
    └─ src/cli/file-info.js::logFileInfoOrDie()
           │
           ├─ path.resolve() - パス解決
           │
           ├─ src/common/get-file-info.js::getFileInfo()
           │      │
           │      ├─ src/utilities/ignore.js::isIgnored()
           │      │
           │      └─ getParser()
           │             ├─ resolveConfig() - 設定ファイル解決
           │             ├─ loadBuiltinPlugins()
           │             ├─ loadPlugins()
           │             └─ inferParser()
           │
           ├─ stringify() - JSON文字列化
           │
           └─ format() - Prettierフォーマット
```

### データフロー図

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

--file-info <path> ─────▶ パス解決 ──────────────────────▶ 絶対パス
                               │
                               ▼
ignoreファイル ──────────▶ isIgnored判定 ─────────────────▶ ignored: boolean
                               │
                               ▼
設定ファイル ───────────▶ パーサー推論 ───────────────────▶ inferredParser: string|null
プラグイン                     │
ファイル拡張子                  ▼
                         JSON構築 ────────────────────────▶ { ignored, inferredParser }
                               │
                               ▼
                         Prettierフォーマット ────────────▶ 整形されたJSON
                               │
                               ▼
                         printToScreen ───────────────────▶ 標準出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| file-info.js | `src/cli/file-info.js` | ソース | CLI実装 |
| get-file-info.js | `src/common/get-file-info.js` | ソース | API実装 |
| cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ソース | オプション定義 |
| index.js | `src/cli/index.js` | ソース | CLIエントリーポイント |
| ignore.js | `src/utilities/ignore.js` | ソース | ignore判定 |
| infer-parser.js | `src/utilities/infer-parser.js` | ソース | パーサー推論 |
