# 機能設計書 3-候補クラスのコンパイル（compileCandidates）

## 概要

本ドキュメントは、候補クラス名の集合からASTノードを生成し、バリアント順序・プロパティ順序に基づいてソートする`compileCandidates`関数の機能設計書である。ユーティリティCSS生成の中核処理を担当する。

### 本機能の処理概要

**業務上の目的・背景**：Tailwind CSSではHTMLのclass属性に記述されたユーティリティクラス名（例: `m-3`, `text-blue-500`, `hover:bg-red-200`）を実際のCSSルールに変換する必要がある。この関数は候補クラス名のイテラブルを受け取り、各候補をパースしてCSSのASTノードを生成し、出力順序を決定する中核処理である。

**機能の利用シーン**：compileAstのbuild関数内部から呼び出され、新しい候補クラスが追加されるたびに全候補からASTノードを再生成する。また、DesignSystemのcandidatesToAst関数からもIntelliSense向けに個別のクラスのAST生成に利用される。

**主要な処理内容**：
1. 候補クラス名をイテレートし、無効な候補をフィルタリングする
2. DesignSystemのparseCandidateで候補文字列をCandidate構造体に変換する
3. DesignSystemのcompileAstNodesで各CandidateからASTノードを生成する
4. バリアント順序（bigint）とプロパティ順序に基づいてASTノードをソートする
5. ソート済みのASTノード配列を返却する

**関連システム・外部連携**：DesignSystemオブジェクトを通じてUtilities、Variants、Themeの各サブシステムと連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Appコンポーネント | 主画面 | className属性のm-3/p-3/border/text-blue-500等の候補クラスからASTノードを生成する |
| 4 | トップページ | 補助画面 | @apply skew-7により指定されたユーティリティクラスのASTノードを生成する |
| 6 | トップページ | 主画面 | className属性のtext-3xl/font-bold/underline/border/ring等の候補クラスからASTノードを生成する |

## 機能種別

データ変換処理（候補クラス名集合 -> ソート済みASTノード配列）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| rawCandidates | Iterable<string> | Yes | 候補クラス名のイテラブル | 空文字列も許容される |
| designSystem | DesignSystem | Yes | デザインシステムオブジェクト | 有効なDesignSystemインスタンス |
| onInvalidCandidate | Function | No | 無効候補検出時のコールバック | - |
| respectImportant | boolean | No | !important適用を尊重するか。デフォルトtrue | - |

### 入力データソース

- compileAstのbuild関数から`allValidCandidates`セットが渡される
- DesignSystemのcandidatesToAst関数から個別クラス名が渡される

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| astNodes | AstNode[] | ソート済みのASTノード配列 |
| nodeSorting | Map<AstNode, SortInfo> | 各ノードのソート情報（プロパティ順序、バリアント順序、候補名） |

### 出力先

- compileAstのbuild関数に返却され、utilitiesNode.nodesに設定される

## 処理フロー

### 処理シーケンス

```
1. 候補のパースフェーズ
   ├─ rawCandidatesをイテレート
   ├─ invalidCandidatesに含まれる候補をスキップ
   ├─ designSystem.parseCandidate で Candidate[] に変換
   ├─ パース失敗時は onInvalidCandidate を呼び出し
   └─ 成功した候補を matches Map に格納
2. ASTノード生成フェーズ
   ├─ CompileAstFlags の設定（respectImportant）
   ├─ designSystem.getVariantOrder() でバリアント順序マップ取得
   ├─ matchesをイテレートし、各Candidateに対して:
   │   ├─ designSystem.compileAstNodes で ASTノード生成
   │   ├─ バリアント順序のビット演算による順序値計算
   │   └─ nodeSortingマップにソート情報を記録
   └─ 生成失敗時は onInvalidCandidate を呼び出し
3. ソートフェーズ
   ├─ バリアント順序で一次ソート（bigint比較）
   ├─ プロパティ順序で二次ソート（配列比較）
   ├─ プロパティ数で三次ソート（多い方が先）
   └─ 候補名で四次ソート（アルファベット順）
```

### フローチャート

```mermaid
flowchart TD
    A[rawCandidates入力] --> B{候補をイテレート}
    B --> C{invalidCandidates?}
    C -->|Yes| D[onInvalidCandidate呼び出し]
    C -->|No| E[parseCandidate実行]
    E --> F{パース成功?}
    F -->|No| D
    F -->|Yes| G[matches Mapに格納]
    D --> B
    G --> B
    B -->|完了| H[matchesをイテレート]
    H --> I[compileAstNodes実行]
    I --> J{ノード生成成功?}
    J -->|No| K[onInvalidCandidate]
    J -->|Yes| L[バリアント順序計算]
    L --> M[nodeSortingに記録]
    M --> H
    H -->|完了| N[astNodes.sort]
    N --> O[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | バリアント順序優先 | ソート時はバリアント順序が最優先される | 常時 |
| BR-02 | プロパティ順序 | 同一バリアント順序の場合、プロパティ順序で決定 | バリアント順序が同じ場合 |
| BR-03 | プロパティ数順 | 同一プロパティ順序の場合、プロパティ数が多い方が先 | プロパティ順序が同じ場合 |
| BR-04 | アルファベット順 | 全て同一の場合、候補名のアルファベット順で決定 | 上記全てが同じ場合 |
| BR-05 | important適用 | respectImportant=trueかつcandidate.importantまたはdesignSystem.important時に!important付与 | build関数からのデフォルト呼び出し時 |
| BR-06 | フォールバックユーティリティ | 通常ユーティリティで生成できなかった場合にフォールバック（types含む'any'）を試行 | 通常ユーティリティで結果が空の場合 |

### 計算ロジック

- **バリアント順序**: `variantOrder |= 1n << BigInt(variantOrderMap.get(variant)!)` でビット演算により各バリアントの位置を示すビットを立てる
- **プロパティ順序**: GLOBAL_PROPERTY_ORDERテーブル内のインデックスに基づくソート。`--tw-sort`宣言による明示的な順序指定も可能
- **比較関数**: `compare(aSorting.candidate, zSorting.candidate)` で自然順ソートを行う

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コールバック通知 | 候補がinvalidCandidatesに含まれる | onInvalidCandidateコールバックを呼び出し |
| - | コールバック通知 | parseCandidateが空配列を返す | onInvalidCandidateコールバックを呼び出し |
| - | コールバック通知 | compileAstNodesが結果を生成しない | onInvalidCandidateコールバックを呼び出し |

### リトライ仕様

リトライは行わない。無効な候補はスキップして処理を継続する。

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

該当なし

## パフォーマンス要件

- compileCandidatesはbuild関数の呼び出し毎に全候補を再処理する。DesignSystem内部のparsedCandidatesおよびcompiledAstNodesのDefaultMapキャッシュにより、個々の候補のパースとASTノード生成はメモ化されている。

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

特になし。

## 備考

- `compileAstNodes`関数は`compileCandidates`と同じファイル（compile.ts）に定義されており、個々のCandidateからASTノードを生成するヘルパーである
- `applyVariant`関数はバリアントの適用ロジックを担当し、arbitrary・compound・staticの各種バリアントを処理する
- `getPropertySort`関数はASTノードのプロパティ順序を決定するヘルパーである

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | candidate.ts | `packages/tailwindcss/src/candidate.ts` | Candidate型とVariant型の構造を理解する |
| 1-2 | property-order.ts | `packages/tailwindcss/src/property-order.ts` | GLOBAL_PROPERTY_ORDER配列の構造を理解する |

**読解のコツ**: `Candidate`型は`kind`フィールドで`arbitrary`（任意プロパティ）、`named`/`static`/`functional`の4種類に分岐する判別共用体（Discriminated Union）パターンを使用している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | compile.ts | `packages/tailwindcss/src/compile.ts` | `compileCandidates`関数（11-121行目）が主要エントリーポイント |

**主要処理フロー**:
1. **27-40行目**: 候補のパースフェーズ。invalidCandidatesチェックとparseCandidate呼び出し
2. **42-46行目**: CompileAstFlagsの設定
3. **48行目**: getVariantOrder()でバリアント順序マップを取得
4. **51-81行目**: ASTノード生成ループ。各CandidateからcompileAstNodes呼び出し
5. **64-67行目**: バリアント順序のビット演算
6. **83-115行目**: ソート処理。バリアント順序 -> プロパティ順序 -> プロパティ数 -> アルファベット順

#### Step 3: compileAstNodes関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | compile.ts | `packages/tailwindcss/src/compile.ts` | `compileAstNodes`関数（123-175行目）。CandidateからASTノードへの変換 |

**主要処理フロー**:
- **128行目**: compileBaseUtilityで基本ユーティリティのAST生成
- **141行目**: セレクタ文字列の生成（`.{エスケープ済み候補名}`）
- **149-151行目**: importantフラグの適用
- **159-166行目**: バリアントの適用（applyVariant関数）

#### Step 4: ソート関連処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | compile.ts | `packages/tailwindcss/src/compile.ts` | `getPropertySort`関数（325-367行目）。プロパティ順序の計算 |

**主要処理フロー**:
- **337-361行目**: ASTノード内の宣言をキューで走査し、GLOBAL_PROPERTY_ORDERからインデックスを取得
- **345-351行目**: `--tw-sort`宣言による明示的な順序指定

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

```
compileCandidates(rawCandidates, designSystem)
    |
    +-- designSystem.parseCandidate()      ... 候補文字列のパース
    |
    +-- designSystem.getVariantOrder()     ... バリアント順序マップ取得
    |
    +-- designSystem.compileAstNodes()     ... ASTノード生成
    |    |
    |    +-- compileAstNodes(candidate, designSystem, flags)
    |         |
    |         +-- compileBaseUtility()     ... 基本ユーティリティ生成
    |         |    +-- utility.compileFn() ... 各ユーティリティのコンパイル関数
    |         |
    |         +-- applyImportant()         ... !important適用
    |         |
    |         +-- applyVariant()           ... バリアント適用
    |              +-- variants.get()      ... バリアント定義取得
    |
    +-- getPropertySort()                  ... プロパティ順序計算
    |
    +-- astNodes.sort()                    ... ソート実行
```

### データフロー図

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

候補クラス名         ──▶  parseCandidate        ──▶  Candidate[]
(rawCandidates)           (candidate.ts)

Candidate           ──▶  compileAstNodes       ──▶  AstNode + PropertySort
                          (compile.ts)

AstNode[]           ──▶  sort (バリアント順序   ──▶  ソート済みAstNode[]
                          + プロパティ順序)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| compile.ts | `packages/tailwindcss/src/compile.ts` | ソース | compileCandidates、compileAstNodes、applyVariant関数 |
| candidate.ts | `packages/tailwindcss/src/candidate.ts` | ソース | Candidate/Variant型定義、parseCandidate関数 |
| property-order.ts | `packages/tailwindcss/src/property-order.ts` | ソース | GLOBAL_PROPERTY_ORDER定義 |
| utilities.ts | `packages/tailwindcss/src/utilities.ts` | ソース | ユーティリティ定義とcompileFn |
| variants.ts | `packages/tailwindcss/src/variants.ts` | ソース | バリアント定義とapplyFn |
| design-system.ts | `packages/tailwindcss/src/design-system.ts` | ソース | DesignSystem経由のAPI |
| ast.ts | `packages/tailwindcss/src/ast.ts` | ソース | AstNode型定義 |
| utils/compare.ts | `packages/tailwindcss/src/utils/compare.ts` | ソース | 自然順ソート比較関数 |
| utils/escape.ts | `packages/tailwindcss/src/utils/escape.ts` | ソース | CSSセレクタエスケープ |
