# 機能設計書 41-クォートスタイル（singleQuote）

## 概要

本ドキュメントは、Prettierのクォートスタイル制御機能（singleQuote）の設計仕様を定義する。

### 本機能の処理概要

singleQuoteオプションは、JavaScript、TypeScript、CSS、YAML等のコード内における文字列リテラルのクォート文字（引用符）をダブルクォート（"）からシングルクォート（'）に変更するかどうかを制御する。

**業務上の目的・背景**：
プロジェクトやチームによってコーディング規約が異なり、シングルクォートを標準とするプロジェクト（AirbnbのJavaScriptスタイルガイドなど）が多く存在する。この機能により、プロジェクト全体で一貫したクォートスタイルを自動的に適用でき、コードレビュー時の不要な指摘を削減し、開発効率を向上させる。

**機能の利用シーン**：
1. 新規プロジェクトのセットアップ時に、チームのコーディング規約に合わせてクォートスタイルを設定する場合
2. 既存コードベースをPrettierに移行する際、既存のクォートスタイルを維持する場合
3. CI/CD環境でコードスタイルの一貫性を検証する場合
4. エディタ統合でリアルタイムにクォートスタイルを適用する場合

**主要な処理内容**：
1. オプション設定の取得とデフォルト値（false = ダブルクォート）の適用
2. 文字列リテラルの解析とクォート文字の判定
3. 文字列内のエスケープシーケンス分析（より少ないエスケープで済むクォートを優先）
4. 優先クォートの決定と文字列の変換
5. 言語固有の特殊処理（JSON、JSX等）

**関連システム・外部連携**：
- EditorConfigとの統合（.editorconfigのquote_type設定を参照）
- 各言語パーサー（Babel、TypeScript、PostCSS等）との連携
- CLI、API、エディタプラグインからの呼び出し

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| singleQuote | boolean | No | シングルクォートを使用するかどうか | true/falseのみ |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| formatted | string | クォートスタイルが適用されたフォーマット済みコード |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. オプション解析
   └─ singleQuoteオプションの値を取得（デフォルト: false）
2. 文字列リテラルの検出
   └─ ASTノードから文字列リテラルを特定
3. 優先クォートの決定
   └─ getPreferredQuote関数で最適なクォートを判定
4. クォート変換の実行
   └─ printString関数で文字列を変換
5. エスケープ処理
   └─ makeString関数で必要なエスケープを適用
```

### フローチャート

```mermaid
flowchart TD
    A[文字列リテラル検出] --> B{singleQuoteの値}
    B -->|true| C[シングルクォート優先]
    B -->|false| D[ダブルクォート優先]
    C --> E{文字列内のクォートを分析}
    D --> E
    E --> F{優先クォートの出現数 > 代替クォートの出現数?}
    F -->|Yes| G[代替クォートを使用]
    F -->|No| H[優先クォートを使用]
    G --> I[エスケープ処理]
    H --> I
    I --> J[出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-41-01 | デフォルトクォート | デフォルトではダブルクォート（"）を使用する | singleQuote未指定または false |
| BR-41-02 | シングルクォート優先 | singleQuote: true の場合、シングルクォートを優先する | singleQuote: true |
| BR-41-03 | エスケープ最小化 | エスケープが少なくて済むクォートを優先して選択する | 常に適用 |
| BR-41-04 | JSON例外 | JSON、JSONC、json-stringifyパーサーでは常にダブルクォートを使用する | parser: json/jsonc/json-stringify |
| BR-41-05 | HTML属性例外 | HTML属性内ではシングルクォートを使用する | __isInHtmlAttribute: true |

### 計算ロジック

クォート選択アルゴリズム（getPreferredQuote関数）:
1. 文字列内の優先クォート出現数をカウント
2. 文字列内の代替クォート出現数をカウント
3. 優先クォート出現数 > 代替クォート出現数 の場合、代替クォートを使用
4. それ以外の場合、優先クォートを使用

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | バリデーションエラー | singleQuoteに不正な値が指定された場合 | 正しいboolean値を指定する |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 文字列ごとの処理は O(n) の時間計算量（n は文字列長）
- メモリ使用量は入力ファイルサイズに比例

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

特になし

## 備考

- JSXのクォートスタイルは別オプション（jsxSingleQuote）で制御される
- ディレクティブ（"use strict"等）は特別な処理が適用される

---

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

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

### 推奨読解順序

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

オプション定義とクォート関連の型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | common-options.evaluate.js | `src/common/common-options.evaluate.js` | singleQuoteオプションの定義（29-34行目） |
| 1-2 | get-preferred-quote.js | `src/utilities/get-preferred-quote.js` | Quote型とクォート定数の定義（1-24行目） |

**読解のコツ**: common-options.evaluate.jsでは、singleQuoteがboolean型でデフォルトfalseであることを確認。

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

オプションが各言語のプリンターにどのように渡されるかを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | options.js | `src/language-js/options.js` | JavaScript言語でのsingleQuoteの参照（65行目） |
| 2-2 | literal.js | `src/language-js/print/literal.js` | 文字列リテラルの出力処理（19-20行目、42-46行目） |

**主要処理フロー**:
1. **19-20行目**: StringLiteralの場合、printString関数を呼び出し
2. **42-46行目**: Literalノードで文字列値の場合、printString関数を呼び出し
3. **74-94行目**: ディレクティブの特別処理（use strict等）

#### Step 3: クォート決定ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | get-preferred-quote.js | `src/utilities/get-preferred-quote.js` | getPreferredQuote関数の実装（31-53行目） |
| 3-2 | print-string.js | `src/utilities/print-string.js` | printString関数の実装（11-49行目） |

**主要処理フロー**:
- **get-preferred-quote.js 31-53行目**: 文字列内のクォート出現数をカウントし、エスケープが最小となるクォートを選択
- **print-string.js 21-34行目**: JSON等の特殊ケース処理
- **print-string.js 36-40行目**: HTML属性内とその他の一般ケースの処理

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

```
format() / formatWithCursor()
    │
    ├─ core.formatWithCursor()
    │      └─ printToDoc()
    │             └─ printer.print()
    │                    └─ printLiteral() [literal.js]
    │                           └─ printString() [print-string.js]
    │                                  └─ getPreferredQuote() [get-preferred-quote.js]
    │                                  └─ makeString() [make-string.js]
    │
    └─ printDirective() [literal.js]
           └─ options.singleQuote を直接参照
```

### データフロー図

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

options.singleQuote ──▶ getPreferredQuote() ──▶ Quote ('/' ")
                       │
rawString ─────────────▶ printString() ────────▶ formattedString
                       │
                       └─ makeString() ────────▶ escapedString
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| common-options.evaluate.js | `src/common/common-options.evaluate.js` | ソース | singleQuoteオプション定義 |
| get-preferred-quote.js | `src/utilities/get-preferred-quote.js` | ソース | 優先クォート決定ロジック |
| print-string.js | `src/utilities/print-string.js` | ソース | 文字列出力処理 |
| make-string.js | `src/utilities/make-string.js` | ソース | 文字列変換・エスケープ処理 |
| literal.js | `src/language-js/print/literal.js` | ソース | JavaScript文字列リテラル出力 |
| options.js | `src/language-js/options.js` | ソース | JavaScript言語オプション定義 |
| jsx.js | `src/language-js/print/jsx.js` | ソース | JSX内の文字列処理 |
| editorconfig-to-prettier.js | `src/config/editorconfig/editorconfig-to-prettier.js` | ソース | EditorConfig統合 |
