# 機能設計書 60-ブレース展開（brace-expansion）

## 概要

本ドキュメントは、`{a,b,c}` 形式のブレース展開を行うユーティリティ関数 `expand` の機能設計を記述する。@source inline() で複数候補を一括指定する際に使用される。

### 本機能の処理概要

**業務上の目的・背景**：Tailwind CSSの `@source inline()` ディレクティブでは、ブレース展開構文を使用して複数の候補クラスを簡潔に指定できる。例えば `@source inline("{bg,text}-{red,blue}-{100,200}")` と記述することで、6つの候補クラスを一括で生成できる。この構文はシェルのブレース展開と同等の展開機能を提供する。

**機能の利用シーン**：`@source inline()` ディレクティブ内で、ブレース展開構文を使用して複数の候補クラスパターンを生成する場合に使用される。数値シーケンス（`{1..10}`）もサポートする。

**主要な処理内容**：
1. パターン文字列内のブレース `{...}` の検出
2. ブレース内容の解析（カンマ区切りリスト or 数値シーケンス）
3. カンマ区切りの場合：segment関数で分割
4. 数値シーケンスの場合：expandSequence関数で数値列を展開
5. 再帰的なブレース展開（ネストされたブレースに対応）
6. 接頭辞・接尾辞との結合

**関連システム・外部連携**：segment関数（utils/segment.ts）、@source inline() ディレクティブ処理

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | ユーティリティ関数のため特定の画面に紐づかない |

## 機能種別

文字列展開 / ユーティリティ関数

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pattern | string | Yes | ブレース展開パターン文字列。例: `"{a,b,c}"`, `"{1..10}"`, `"bg-{red,blue}-{100,200}"` | ブレースがバランスしていること |

### 入力データソース

- @source inline() ディレクティブのパラメータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | string[] | 展開されたパターン文字列の配列 |

### 出力先

呼び出し元への戻り値

## 処理フロー

### 処理シーケンス

```
1. ブレース検出
   └─ pattern.indexOf('{') で最初の開きブレースを検出
   └─ ブレースなしの場合は [pattern] を返す（再帰の終端）
2. 接頭辞の抽出
   └─ ブレース前の文字列を pre として抽出
3. 閉じブレースの検出
   └─ ネスト深度を追跡しながら対応する閉じブレースを検出
4. ブレース内容の解析
   └─ 数値シーケンス判定（NUMERICAL_RANGE正規表現）
   └─ シーケンスの場合: expandSequence() で数値列生成
   └─ リストの場合: segment(inside, ',') でカンマ区切り分割
5. 各パーツの再帰展開
   └─ expand(part) でネストされたブレースを再帰展開
6. 接尾辞の再帰展開
   └─ expand(post) で閉じブレース後の残りを再帰展開
7. 結合
   └─ pre + part + tail の全組み合わせを生成
```

### フローチャート

```mermaid
flowchart TD
    A["expand(pattern)"] --> B{ブレースあり?}
    B -->|No| C["[pattern] を返す"]
    B -->|Yes| D[pre + rest に分割]
    D --> E[対応する閉じブレースを検出]
    E --> F{バランスしている?}
    F -->|No| G[Error: not balanced]
    F -->|Yes| H[inside + post に分割]
    H --> I{数値シーケンス?}
    I -->|Yes| J["expandSequence(inside)"]
    I -->|No| K["segment(inside, ',')"]
    J --> L["parts.flatMap(expand)"]
    K --> L
    L --> M["expand(post) → expandedTail"]
    M --> N[pre + part + tail の全組み合わせ]
    N --> O[result配列を返す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-60-01 | ブレースなし短絡 | パターンに `{` が含まれない場合、そのパターン自体を配列で返す | expand呼び出し時 |
| BR-60-02 | ネスト対応 | ブレースのネスト深度を追跡し、正しい対応関係で閉じブレースを検出する | ブレース検出時 |
| BR-60-03 | バランスチェック | 開きブレースと閉じブレースがバランスしていない場合はErrorをthrow | ブレース検出時 |
| BR-60-04 | 数値シーケンス | `{start..end}` または `{start..end..step}` 形式の数値範囲展開に対応 | ブレース内容が数値シーケンスパターンに一致する場合 |
| BR-60-05 | ステップ自動決定 | stepが未指定の場合、start<=endなら1、そうでなければ-1を使用 | expandSequence内 |
| BR-60-06 | ステップ方向自動補正 | stepの符号が展開方向と一致しない場合、符号を反転する | expandSequence内 |
| BR-60-07 | ステップ0エラー | stepが0の場合はErrorをthrow | expandSequence内 |
| BR-60-08 | 再帰展開 | パーツ内のブレースと接尾辞内のブレースを再帰的に展開する | expand内 |

### 計算ロジック

- 数値シーケンスの正規表現: `/^(-?\d+)\.\.(-?\d+)(?:\.\.(-?\d+))?$/`
  - `{1..5}` → [1, 2, 3, 4, 5]
  - `{1..10..2}` → [1, 3, 5, 7, 9]
  - `{5..1}` → [5, 4, 3, 2, 1]

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | バランスエラー | 閉じブレースが見つからない場合 | Error("The pattern `...` is not balanced.") をthrow |
| - | ステップ0エラー | 数値シーケンスのstepが0の場合 | Error("Step cannot be zero in sequence expansion.") をthrow |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 再帰的な展開のため、深くネストしたパターンや大きな数値範囲では組み合わせ爆発に注意
- segment関数を使用してカンマ分割時の括弧ネストを考慮

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

- ユーザー入力によるパターンが大量の展開結果を生成する可能性がある（DoSリスク）

## 備考

- シェルのブレース展開（bash等）と同等の機能を提供
- 負の数値にも対応（-1..1 → [-1, 0, 1]）
- segment関数はカンマ分割時に括弧のネストを考慮するため、`{a,{b,c}}` のようなパターンも正しく処理される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | brace-expansion.ts | `packages/tailwindcss/src/utils/brace-expansion.ts` | NUMERICAL_RANGE正規表現（3行目）: 数値シーケンスの判定パターン |

**読解のコツ**: 正規表現 `/^(-?\d+)\.\.(-?\d+)(?:\.\.(-?\d+))?$/` のキャプチャグループ：1番目=開始値、2番目=終了値、3番目=ステップ（オプション）。負の値もサポート。

#### Step 2: メイン関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | brace-expansion.ts | `packages/tailwindcss/src/utils/brace-expansion.ts` | expand関数（5-53行目）: ブレース展開のメインロジック |

**主要処理フロー**:
1. **6-7行目**: ブレース検出。なければ [pattern] を返す
2. **10-11行目**: 接頭辞（pre）と残り（rest）の分割
3. **14-27行目**: ネスト深度追跡による閉じブレース検出
4. **29-31行目**: バランスチェック
5. **33-41行目**: inside（ブレース内）とpost（ブレース後）の分割、シーケンス判定
6. **43行目**: パーツの再帰展開
7. **45-52行目**: 接尾辞の再帰展開と全組み合わせ生成

#### Step 3: 数値シーケンス展開を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | brace-expansion.ts | `packages/tailwindcss/src/utils/brace-expansion.ts` | isSequence（55-57行目）とexpandSequence（62-91行目）: 数値範囲展開 |

**主要処理フロー**:
- **63-66行目**: 正規表現マッチとキャプチャ
- **67-68行目**: start, end, stepの解析
- **75-77行目**: stepが未定義の場合のデフォルト決定
- **78-80行目**: step=0のエラーチェック
- **82-84行目**: ステップ方向の自動補正
- **86-88行目**: forループによる数値列生成

#### Step 4: 依存ユーティリティを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | segment.ts | `packages/tailwindcss/src/utils/segment.ts` | segment関数: カンマ区切り分割（括弧ネスト考慮） |

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

```
expand(pattern)
    |
    +-- [ブレースなし] → return [pattern]
    |
    +-- [ブレースあり]
            |
            +-- isSequence(inside)
            |       +-- [true] → expandSequence(inside)
            |       +-- [false] → segment(inside, ',')
            |
            +-- parts.flatMap(expand)  [再帰: パーツ内ブレース]
            |
            +-- expand(post)           [再帰: 接尾辞ブレース]
            |
            +-- pre + part + tail      [全組み合わせ生成]
```

### データフロー図

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

"bg-{red,blue}-{100,200}"
        |
        v
    expand()  ───────▶  "bg-" + ["red", "blue"] + "-{100,200}"
        |
        v
    [再帰]    ───────▶  "-" + ["100", "200"]
        |
        v
    [組み合わせ]  ───▶  ["bg-red-100", "bg-red-200",
                         "bg-blue-100", "bg-blue-200"]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| brace-expansion.ts | `packages/tailwindcss/src/utils/brace-expansion.ts` | ソース | ブレース展開のメイン実装 |
| segment.ts | `packages/tailwindcss/src/utils/segment.ts` | ソース | 括弧ネスト考慮のカンマ分割 |
