# 機能設計書 42-末尾カンマ（trailingComma）

## 概要

本ドキュメントは、Prettierの末尾カンマ制御機能（trailingComma）の設計仕様を定義する。

### 本機能の処理概要

trailingCommaオプションは、複数行にわたる配列、オブジェクト、関数パラメータ、import/export文などの最後の要素の後にカンマを付けるかどうかを制御する。ES5互換性やコードの可読性、Git差分の最小化などを考慮した設定が可能。

**業務上の目的・背景**：
末尾カンマ（trailing comma / dangling comma）は、コードの変更差分を最小化し、要素の追加・削除時のGit diffをクリーンに保つために重要な役割を果たす。また、ES5環境との互換性を維持しながらモダンなコーディングスタイルを適用したいプロジェクトにも対応できる。この機能により、チームのポリシーに合わせた一貫した末尾カンマスタイルを自動的に適用できる。

**機能の利用シーン**：
1. モダンJavaScript環境で末尾カンマを一貫して適用したい場合（all）
2. ES5環境との互換性を維持しながら末尾カンマを使用したい場合（es5）
3. レガシー環境向けに末尾カンマを完全に除去したい場合（none）
4. Git差分を最小化してコードレビューを効率化したい場合

**主要な処理内容**：
1. trailingCommaオプションの値取得（all/es5/none）
2. 複数行コンテキストの判定
3. ES5互換性チェック（関数パラメータ等）
4. 末尾カンマの挿入または削除
5. 特殊ケース処理（rest parameters等）

**関連システム・外部連携**：
- 各言語プリンター（JavaScript、TypeScript、JSON、CSS、YAML等）
- CLI、API、エディタプラグインからの呼び出し

**権限による制御**：
特になし。全てのユーザーが同一の機能を使用可能。

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| trailingComma | string | No | 末尾カンマの出力方法 | "all" / "es5" / "none" のいずれか |

### 入力データソース

- 設定ファイル（.prettierrc、prettier.config.js、package.json等）
- CLI引数（--trailing-comma）
- API呼び出し時のオプションオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| formatted | string | 末尾カンマが適切に制御されたフォーマット済みコード |

### 出力先

- 標準出力（CLIの場合）
- ファイル（--write オプション使用時）
- API戻り値

## 処理フロー

### 処理シーケンス

```
1. オプション解析
   └─ trailingCommaオプションの値を取得（デフォルト: "all"）
2. 複数行判定
   └─ 要素が複数行にわたるかどうかを判定
3. 互換性チェック
   └─ "es5"の場合、関数パラメータ等でカンマを省略
4. 特殊ケース判定
   └─ RestElement等、末尾カンマが許容されない構文をチェック
5. カンマ出力
   └─ shouldPrintTrailingComma関数で判定し出力
```

### フローチャート

```mermaid
flowchart TD
    A[複数行要素検出] --> B{trailingCommaの値}
    B -->|all| C[関数パラメータ含む全てに末尾カンマ]
    B -->|es5| D[ES5互換箇所のみ末尾カンマ]
    B -->|none| E[末尾カンマなし]
    C --> F{RestElement?}
    D --> F
    E --> G[出力]
    F -->|Yes| H[カンマ省略]
    F -->|No| I[カンマ出力]
    H --> G
    I --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-42-01 | デフォルト設定 | デフォルトでは"all"（関数パラメータ含む全てに末尾カンマ） | trailingComma未指定 |
| BR-42-02 | ES5互換モード | "es5"ではオブジェクト、配列等ES5で有効な箇所のみに末尾カンマ | trailingComma: "es5" |
| BR-42-03 | 末尾カンマなし | "none"では末尾カンマを出力しない | trailingComma: "none" |
| BR-42-04 | RestElement例外 | RestElement（...args）の後には末尾カンマを付けない | 常に適用 |
| BR-42-05 | 単一行除外 | 単一行に収まる場合は末尾カンマを付けない | 常に適用 |

### 計算ロジック

shouldPrintTrailingComma関数のロジック:
```javascript
function shouldPrintTrailingComma(options, level = "es5") {
  return (
    (options.trailingComma === "es5" && level === "es5") ||
    (options.trailingComma === "all" && (level === "all" || level === "es5"))
  );
}
```

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

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

該当なし（本機能はデータベース操作を行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | バリデーションエラー | trailingCommaに不正な値が指定された場合 | "all"/"es5"/"none"のいずれかを指定する |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 処理時間への影響は軽微
- 既存のAST走査に統合されている

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

特になし

## 備考

- TypeScriptの型パラメータ、import/export文にも適用される
- JSON/JSON5では言語仕様に従い独自の処理が行われる

---

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

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

### 推奨読解順序

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

オプション定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | options.js | `src/language-js/options.js` | trailingCommaオプションの定義（93-111行目） |

**読解のコツ**: trailingCommaはchoice型で、"all"、"es5"、"none"の3つの選択肢がある。デフォルトは"all"。

#### Step 2: 判定ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | should-print-trailing-comma.js | `src/language-js/utilities/should-print-trailing-comma.js` | shouldPrintTrailingComma関数（1-13行目） |

**主要処理フロー**:
1. **6-10行目**: levelパラメータとオプション値を比較して末尾カンマ出力を判定
2. "es5" && level === "es5" → true
3. "all" && (level === "all" || level === "es5") → true

#### Step 3: 呼び出し箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | array.js | `src/language-js/print/array.js` | 配列での末尾カンマ処理 |
| 3-2 | function-parameters.js | `src/language-js/print/function-parameters.js` | 関数パラメータでの処理（188行目） |
| 3-3 | object.js | `src/language-js/print/object.js` | オブジェクトでの処理（151行目） |
| 3-4 | type-parameters.js | `src/language-js/print/type-parameters.js` | 型パラメータでの処理 |

**主要処理フロー**:
- **function-parameters.js 188行目**: RestParameterがない場合のみprintTrailingComma(options, "all")を呼び出し
- **object.js 151行目**: canHaveTrailingSeparatorを確認後にprintTrailingComma(options)を呼び出し

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

```
format() / formatWithCursor()
    │
    ├─ core.formatWithCursor()
    │      └─ printToDoc()
    │             └─ printer.print()
    │                    │
    │                    ├─ printArray() [array.js]
    │                    │      └─ shouldPrintTrailingComma()
    │                    │
    │                    ├─ printFunctionParameters() [function-parameters.js]
    │                    │      └─ printTrailingComma() → shouldPrintTrailingComma()
    │                    │
    │                    ├─ printObject() [object.js]
    │                    │      └─ printTrailingComma() → shouldPrintTrailingComma()
    │                    │
    │                    └─ printTypeParameters() [type-parameters.js]
    │                           └─ shouldPrintTrailingComma()
```

### データフロー図

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

options.trailingComma ──▶ shouldPrintTrailingComma() ──▶ boolean
                         │
level ("es5"/"all") ─────┘
                         │
                         ▼
                    printTrailingComma() ──▶ ifBreak(",", "")
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| options.js | `src/language-js/options.js` | ソース | trailingCommaオプション定義 |
| should-print-trailing-comma.js | `src/language-js/utilities/should-print-trailing-comma.js` | ソース | 末尾カンマ出力判定ロジック |
| miscellaneous.js | `src/language-js/print/miscellaneous.js` | ソース | printTrailingComma関数 |
| array.js | `src/language-js/print/array.js` | ソース | 配列リテラルの末尾カンマ処理 |
| object.js | `src/language-js/print/object.js` | ソース | オブジェクトリテラルの末尾カンマ処理 |
| function-parameters.js | `src/language-js/print/function-parameters.js` | ソース | 関数パラメータの末尾カンマ処理 |
| type-parameters.js | `src/language-js/print/type-parameters.js` | ソース | 型パラメータの末尾カンマ処理 |
| call-arguments.js | `src/language-js/print/call-arguments.js` | ソース | 関数呼び出し引数の末尾カンマ処理 |
| index-signature.js | `src/language-js/print/index-signature.js` | ソース | インデックスシグネチャの末尾カンマ処理 |
| normalize-format-options.js | `src/main/normalize-format-options.js` | ソース | オプション正規化処理 |
