# 機能設計書 53-Prose折り返し（proseWrap）

## 概要

本ドキュメントは、Prettierの`proseWrap`オプションに関する機能設計書である。このオプションは、MarkdownやYAMLなどの散文（Prose）テキストの折り返し方法を制御する。printWidthを超える行を自動的に折り返すか、元のテキストの改行を維持するかを選択できる。

### 本機能の処理概要

**業務上の目的・背景**：Markdownドキュメントの管理において、行の折り返し方針はプロジェクトごとに異なる。Gitでの差分管理を容易にするために行を折り返すチームもあれば、エディタのソフトラップに任せるために折り返さないチームもある。このオプションにより、プロジェクトの方針に合わせた柔軟なフォーマットが可能になる。

**機能の利用シーン**：Markdownファイル、YAMLファイルのフォーマット時に使用される。特に、ドキュメント管理システムやCMSと連携する場合、一貫した行長管理が求められる場面で活用される。

**主要な処理内容**：
1. オプション値（always/never/preserve）の読み込み
2. 散文テキストのパース
3. 空白文字（スペース、改行）の処理方法を決定
4. オプション値に基づいて折り返しまたは維持を適用

**関連システム・外部連携**：Markdownパーサー、YAMLパーサーと連携して動作する。

**権限による制御**：権限による制御は存在しない。設定ファイルまたはCLIオプションで指定する。

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| proseWrap | choice | No | 散文テキストの折り返し方法 | "always", "never", "preserve"のいずれか |

### 入力データソース

- 設定ファイル（.prettierrc、prettier.config.js等）
- CLIオプション（--prose-wrap）
- プログラマティックAPI呼び出し時のオプションオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| formattedCode | string | 折り返し設定が適用されたフォーマット済みテキスト |

### 出力先

フォーマット結果は呼び出し元に返却される（標準出力、ファイル、API戻り値）。

## 処理フロー

### 処理シーケンス

```
1. オプション解析
   └─ proseWrapオプションの値を取得（デフォルト: "preserve"）
2. テキストパース
   └─ Markdown/YAMLパーサーでテキストを解析
3. 空白・改行の処理
   └─ printWhitespace関数でproseWrapに基づいて処理
4. 行折り返し判定
   └─ isBreakable関数で折り返し可否を判定
5. 出力生成
   └─ line/softline/hardline/""/スペースを適切に配置
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[テキストをパース]
    B --> C{proseWrap値は?}
    C -->|preserve| D[元の改行を維持]
    C -->|always| E{printWidthを超える?}
    C -->|never| F[改行をスペースに変換]
    E -->|Yes| G[折り返しを適用]
    E -->|No| H[1行で出力]
    D --> I[出力]
    F --> I
    G --> I
    H --> I
    I --> J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-53-1 | デフォルト動作 | 元の改行を維持する | proseWrap = "preserve"（デフォルト） |
| BR-53-2 | 常に折り返し | printWidthを超える場合に折り返し | proseWrap = "always" |
| BR-53-3 | 折り返さない | 改行をスペースに変換、1行で出力 | proseWrap = "never" |
| BR-53-4 | 特殊コンテキスト | 見出し・リンク・テーブルセル内は折り返さない | 常時 |
| BR-53-5 | CJK言語対応 | 中国語・日本語間の改行はスペースに変換しない | CJK文字間 |

### 計算ロジック

特別な計算ロジックは存在しない。

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

データベース操作は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 値エラー | 未定義の値が指定された場合 | Prettierのオプション検証でエラーが発生 |

### リトライ仕様

リトライは不要（同期的な設定適用処理）。

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

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

## パフォーマンス要件

テキスト処理のため、大量のテキストがある場合はパフォーマンスに影響する可能性がある。

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

セキュリティに関する特別な考慮事項は存在しない。

## 備考

- Markdown、YAMLで使用される。
- テーブルセル内、リンク内では常に折り返しが無効になる。
- 中国語・日本語（CJ）と非CJK文字間の空白処理には特別なロジックがある。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | common-options.evaluate.js | `src/common/common-options.evaluate.js` | proseWrapオプションの定義 |

**読解のコツ**: このファイルでは、proseWrapがchoice型で3つの選択肢（always, never, preserve）を持つことを確認する。

#### Step 2: Markdown実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | whitespace.js | `src/language-markdown/print/whitespace.js` | printWhitespace、isBreakable関数 |
| 2-2 | mdast.js | `src/language-markdown/print/mdast.js` | proseWrapの参照箇所 |

**主要処理フロー（whitespace.js）**:
1. **181-192行目**: isBreakable関数でproseWrap !== "always"の場合はfalseを返す
2. **252-266行目**: printWhitespace関数でproseWrapに基づいて出力を決定
3. **253-255行目**: preserve時に改行をhardlineとして出力
4. **261-262行目**: isBreakableの結果に基づいてline/softlineを選択

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | utilities.js | `src/language-yaml/utilities.js` | YAML用のproseWrap処理 |

**主要処理フロー**:
- **168行目**: preserve時の特別処理
- **194行目**: never時の処理
- **231行目**: blockLiteral内での処理
- **271行目**: never時の単一行出力

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

```
Markdown処理:
printMdast (mdast.js)
    │
    ├─ printWhitespace (whitespace.js:252)
    │      ├─ proseWrap === "preserve" チェック
    │      ├─ isBreakable 呼び出し
    │      │      └─ proseWrap !== "always" チェック
    │      └─ line / softline / hardline 選択
    │
    └─ options.proseWrap 参照（複数箇所）

YAML処理:
print関数 (utilities.js)
    │
    └─ options.proseWrap 参照
           ├─ "preserve" 処理
           ├─ "never" 処理
           └─ "always" 処理（デフォルト）
```

### データフロー図

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

オプション設定 ───▶ printWhitespace関数 ───▶ 空白文字のDoc表現
(proseWrap)           (whitespace.js)         (hardline/line/softline/" ")
        │
        ▼
Markdown/YAML ───▶ isBreakable判定 ───▶ 折り返し可否
コンテンツ               (whitespace.js)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| common-options.evaluate.js | `src/common/common-options.evaluate.js` | ソース | オプション定義（35-54行目） |
| options.js | `src/language-markdown/options.js` | ソース | Markdownオプションへの参照 |
| options.js | `src/language-yaml/options.js` | ソース | YAMLオプションへの参照 |
| whitespace.js | `src/language-markdown/print/whitespace.js` | ソース | Markdown空白処理ロジック |
| mdast.js | `src/language-markdown/print/mdast.js` | ソース | MarkdownノードPrinter |
| utilities.js | `src/language-yaml/utilities.js` | ソース | YAML用ユーティリティ |
| index.d.ts | `src/index.d.ts` | 型定義 | TypeScript型定義（398行目） |
