# 機能設計書 2-AST入力のコンパイル（compileAst）

## 概要

本ドキュメントは、パース済みのAST配列を入力として受け取り、候補クラスからユーティリティCSSを生成する`build`関数を返す`compileAst`関数の機能設計書である。`compile`関数の内部実装であり、外部からも直接利用可能なAPIとして公開されている。

### 本機能の処理概要

**業務上の目的・背景**：`compile`関数はCSS文字列のパースとAST処理を一括で行うが、既にパース済みのASTを持つ呼び出し元（ビルドツール統合など）が直接AST処理から開始できるようにするためのAPI。CSS文字列のパース処理を省略でき、ASTの再利用が可能になる。

**機能の利用シーン**：ビルドツールがAST操作を独自に行った後、Tailwind CSSのディレクティブ処理とユーティリティ生成のみを実行したい場合に利用される。`compile`関数もこの`compileAst`関数を内部で使用している。

**主要な処理内容**：
1. parseCss関数を呼び出してディレクティブ処理とDesignSystem構築を行う
2. バージョンコメントをASTの先頭に追加する（テスト環境を除く）
3. インライン候補の初期登録を行う
4. 候補クラスの差分を管理するbuild関数をクロージャとして生成する
5. sources、root、features情報を返却する

**関連システム・外部連携**：`compile`関数と同じくloadModule/loadStylesheetコールバックを通じてファイルシステムと連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | compileAstは内部API。compile関数経由で間接的に全画面に関連 |

## 機能種別

データ変換処理（AST -> 候補クラス付きAST -> 最適化済みAST）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| input | AstNode[] | Yes | パース済みのAST配列 | 有効なAstNode配列 |
| opts.base | string | No | ベースディレクトリパス | デフォルトは空文字列 |
| opts.from | string | No | 入力CSSファイルのパス | ファイルパス文字列 |
| opts.polyfills | Polyfills | No | ポリフィル設定 | ビットフラグ |
| opts.loadModule | Function | No | JSモジュール読み込みコールバック | 未指定時はエラーをスロー |
| opts.loadStylesheet | Function | No | スタイルシート読み込みコールバック | 未指定時はエラーをスロー |

### 入力データソース

- compile関数からパース済みASTが渡される
- 外部からは直接AstNode配列を構築して渡すことも可能

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| sources | Array<{base, pattern, negated}> | スキャン対象のソースパス情報 |
| root | null \| 'none' \| {base, pattern} | ルートソース設定 |
| features | Features | 使用された機能フラグ |
| build | (candidates: string[]) => AstNode[] | 候補クラスからAST配列を生成する関数 |

### 出力先

- build関数の戻り値としてAstNode配列が返される（compile関数とは異なりCSS文字列への変換は行わない）

## 処理フロー

### 処理シーケンス

```
1. parseCss呼び出し
   └─ ディレクティブ処理、DesignSystem構築
2. バージョンコメント追加
   └─ テスト環境以外で "tailwindcss v{version}" コメントを先頭に挿入
3. クロージャ変数初期化
   ├─ allValidCandidates: Set<string>
   ├─ compiled: AstNode[] | null
   └─ previousAstNodeCount: number
4. インライン候補の初期登録
   └─ @source inline() で指定された候補を allValidCandidates に追加
5. build関数のクロージャ返却
   ├─ features === None の場合: 入力をそのまま返却
   ├─ utilitiesNode なしの場合: 静的AST最適化のみ
   ├─ 新候補の差分検出
   ├─ compileCandidates による AST生成
   ├─ ソースロケーション付与
   ├─ 差分なしの場合: キャッシュ返却
   └─ optimizeAst による AST最適化
```

### フローチャート

```mermaid
flowchart TD
    A[AstNode[] 入力] --> B[parseCss: ディレクティブ処理]
    B --> C[バージョンコメント追加]
    C --> D[クロージャ変数初期化]
    D --> E[インライン候補登録]
    E --> F[build関数返却]
    F --> G{build呼び出し}
    G --> H{features === None?}
    H -->|Yes| I[入力をそのまま返却]
    H -->|No| J{utilitiesNodeあり?}
    J -->|No| K[静的AST最適化して返却]
    J -->|Yes| L[新候補の差分検出]
    L --> M{変化あり?}
    M -->|No| N[キャッシュ返却]
    M -->|Yes| O[compileCandidates実行]
    O --> P[ソースロケーション付与]
    P --> Q{ASTノード数変化?}
    Q -->|No| R[キャッシュ返却]
    Q -->|Yes| S[utilitiesNode.nodes更新]
    S --> T[optimizeAst実行]
    T --> U[最適化済みAST返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | features無効時の短絡 | featuresがNoneの場合、入力ASTをそのまま返却する | ディレクティブが一つも使用されていない場合 |
| BR-02 | utilities無効時の静的最適化 | utilitiesNodeがない場合、静的ASTのoptimizeAstのみ実行 | @tailwind utilitiesが存在しない場合 |
| BR-03 | 差分なし時のキャッシュ | 候補クラスに変化がない場合、前回の最適化結果を返却 | build関数の連続呼び出し時 |
| BR-04 | CSS変数の使用追跡 | `--`で始まる候補はCSS変数として扱い、テーマ変数の使用をマーク | 候補が`--`で始まる場合 |
| BR-05 | 無効候補の永続記録 | 無効と判定された候補はinvalidCandidatesセットに記録される | 候補のパースに失敗した場合 |

### 計算ロジック

- 差分検出: `allValidCandidates.size`の変化、または`defaultDidChange`フラグにより判定
- ASTノード数比較: `previousAstNodeCount !== newNodes.length`で再コンパイルの必要性を判定

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Error | parseCss内で発生する各種エラー | No.1参照 |

### リトライ仕様

リトライは行わない。

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

該当なし

## パフォーマンス要件

- build関数は3段階のキャッシュ判定を行い、不要な再コンパイルを回避する
  1. 候補の差分なし → キャッシュ返却
  2. ASTノード数が同じかつCSS変数の追加なし → キャッシュ返却
  3. 変化あり → 再コンパイル

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

No.1と同様。

## 備考

- `compileAst`はAST配列を返すため、呼び出し元がCSS文字列への変換タイミングを制御できる
- `compile`関数はこの関数のラッパーであり、toCssによるCSS文字列変換とソースマップ生成を追加する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ast.ts | `packages/tailwindcss/src/ast.ts` | AstNode型の構造、特にContext型とAtRoot型を理解する |
| 1-2 | index.ts | `packages/tailwindcss/src/index.ts` | Root型（106-114行目）とFeatures列挙型（116-139行目）を理解する |

**読解のコツ**: `Root`型はUnion型で、null（未指定）、'none'（明示的に無効）、{base, pattern}（明示的なパス指定）の3つの状態を持つ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/tailwindcss/src/index.ts` | `compileAst`関数（709-815行目）がエントリーポイント |

**主要処理フロー**:
1. **718-719行目**: parseCssの戻り値をデストラクチャリングで受け取る
2. **721-723行目**: テスト環境以外でバージョンコメントを追加
3. **733-734行目**: キャッシュ変数の初期化
4. **738-743行目**: インライン候補の初期登録
5. **749行目**: build関数の定義開始

#### Step 3: build関数のクロージャロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/tailwindcss/src/index.ts` | build関数内部（749-813行目）のキャッシュ判定と候補処理ロジック |

**主要処理フロー**:
- **750-752行目**: features === Noneの短絡処理
- **754-757行目**: utilitiesNode無しの場合の静的最適化
- **765-776行目**: 新候補の追加処理。`--`始まりはCSS変数として特別扱い
- **780-783行目**: 差分なし時のキャッシュ返却
- **785-787行目**: compileCandidatesによる新しいASTノード生成
- **789-797行目**: ソースロケーションの付与（opts.fromが指定されている場合）
- **802-804行目**: ASTノード数比較によるキャッシュ判定
- **809行目**: utilitiesNode.nodesへの新ノード設定
- **811行目**: optimizeAstによる最終的なAST最適化

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

```
compileAst(input, opts)
    |
    +-- parseCss(input, opts)       ... ディレクティブ処理（No.1参照）
    |
    +-- comment()                   ... バージョンコメント生成
    |
    +-- build(newRawCandidates)     ... クロージャ
         |
         +-- compileCandidates()   ... 候補からASTノード生成
         |
         +-- walk()                ... ソースロケーション付与
         |
         +-- optimizeAst()         ... AST最適化
```

### データフロー図

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

AstNode[]         ──▶  parseCss              ──▶  DesignSystem
                       (index.ts)                  sources[]
                                                   utilitiesNode

候補クラス名[]     ──▶  build(candidates)     ──▶  AstNode[]
                       (クロージャ)                  （最適化済み）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/tailwindcss/src/index.ts` | ソース | compileAst関数の定義（709-815行目） |
| compile.ts | `packages/tailwindcss/src/compile.ts` | ソース | compileCandidates関数 |
| ast.ts | `packages/tailwindcss/src/ast.ts` | ソース | ASTノード操作、optimizeAst、toCss |
| design-system.ts | `packages/tailwindcss/src/design-system.ts` | ソース | DesignSystem構築 |
| walk.ts | `packages/tailwindcss/src/walk.ts` | ソース | ASTウォーカー |
