# 機能設計書 8-AST構築・操作

## 概要

本ドキュメントは、StyleRule・AtRule・Declaration・Comment・Context・AtRoot等のASTノード生成関数群と、ASTをCSS文字列に変換するtoCss関数、AST最適化のoptimizeAst関数を提供するast.tsモジュールの機能設計書である。

### 本機能の処理概要

**業務上の目的・背景**：Tailwind CSSのコンパイルパイプラインでは、CSSを抽象構文木（AST）として内部表現し、ディレクティブ処理・ユーティリティ生成・最適化の各段階でASTを操作する。ast.tsモジュールはAST操作の基盤を提供し、ノード生成・クローン・CSS文字列変換・最適化の機能を集約する。

**機能の利用シーン**：コンパイルパイプラインのほぼ全ての段階で使用される。CSSパーサーがノードを生成し、ディレクティブ処理やユーティリティ生成でノードを操作し、最終段階でtoCssによりCSS文字列に変換する。optimizeAstはビルド完了時にAST全体の最適化を行う。

**主要な処理内容**：
1. ASTノード型定義（StyleRule, AtRule, Declaration, Comment, Context, AtRoot）
2. ノード生成ファクトリ関数（styleRule, atRule, rule, decl, comment, context, atRoot）
3. ノードクローン関数（cloneAstNode）
4. CSSコンテキスト解決関数（cssContext）
5. AST最適化関数（optimizeAst）- 未使用テーマ変数の除去、@propertyポリフィル生成、color-mixポリフィル生成
6. CSS文字列変換関数（toCss）- ソースマップ対応のトラッキング機能付き

**関連システム・外部連携**：特になし。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 全画面のCSSコンパイルで間接的に使用される基盤モジュール |

## 機能種別

データ構造定義 / データ変換処理

## 入力仕様

### 入力パラメータ

#### styleRule関数
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| selector | string | Yes | CSSセレクタ文字列 | - |
| nodes | AstNode[] | No | 子ノード配列。デフォルト空配列 | - |

#### atRule関数
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | at-rule名（@付き） | - |
| params | string | No | パラメータ文字列。デフォルト空文字列 | - |
| nodes | AstNode[] | No | 子ノード配列。デフォルト空配列 | - |

#### optimizeAst関数
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ast | AstNode[] | Yes | 最適化対象のAST配列 | - |
| designSystem | DesignSystem | Yes | デザインシステムオブジェクト | - |
| polyfills | Polyfills | No | ポリフィル設定。デフォルトPolyfills.All | - |

#### toCss関数
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ast | AstNode[] | Yes | 変換対象のAST配列 | - |
| track | boolean | No | ソースマップ用の位置トラッキング有無 | - |

### 入力データソース

- CSSパーサーの出力、コンパイルパイプラインの各段階で生成されたAST

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ノード生成関数の戻り値 | AstNode | 各種ASTノード |
| optimizeAstの戻り値 | AstNode[] | 最適化済みAST配列 |
| toCssの戻り値 | string | CSS文字列 |

### 出力先

- コンパイルパイプラインの次の処理段階、または最終的なCSS出力

## 処理フロー

### 処理シーケンス（optimizeAst）

```
1. transform関数による再帰的AST変換
   ├─ Declaration: --tw-sortとvalue未定義の除外、テーマ変数追跡、CSS変数使用追跡、
   │              animation名追跡、color-mix検出
   ├─ Rule: 子ノード変換、重複宣言除去、セレクタ&のフラット化
   ├─ AtRule(@property): @propertyポリフィル生成、重複除去
   ├─ AtRule(その他): @keyframesコンテキスト、@supports color-mixコンテキスト
   ├─ AtRoot: 子ノードを最上位に展開
   ├─ Context: referenceの場合は除外、それ以外はコンテキスト継承
   └─ Comment: そのまま保持
2. 未使用テーマ変数の除去
   └─ isVariableUsed関数で使用状況を判定し、未使用変数を親から削除
3. 未使用@keyframesの除去
   └─ usedKeyframeNamesセットに含まれないキーフレームを削除
4. color-mixポリフィル生成（Polyfills.ColorMix有効時）
   └─ color-mix()を含む宣言にフォールバック値と@supportsラッパーを生成
5. @propertyポリフィル生成（Polyfills.AtProperty有効時）
   └─ :rootと*に初期値のフォールバック宣言を生成
```

### フローチャート

```mermaid
flowchart TD
    A[AST入力] --> B[transform: 再帰的変換]
    B --> C[未使用テーマ変数除去]
    C --> D[未使用keyframes除去]
    D --> E{ColorMixポリフィル有効?}
    E -->|Yes| F[color-mixフォールバック生成]
    E -->|No| G{AtPropertyポリフィル有効?}
    F --> G
    G -->|Yes| H[@propertyフォールバック生成]
    G -->|No| I[最適化済みAST返却]
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | --tw-sort除外 | `--tw-sort`プロパティの宣言は出力から除外される | 宣言のプロパティが--tw-sortの場合 |
| BR-02 | 値未定義の除外 | valueがundefinedまたはnullの宣言は除外される | 宣言のvalueがundefined/nullの場合 |
| BR-03 | initial値の除外 | テーマコンテキスト内でvalueが'initial'の変数宣言は除外される | @theme内で値がinitialの場合 |
| BR-04 | 重複宣言の除去 | 同一ルール内の重複宣言は最後のものを保持する | 同一property:value:importantの宣言が複数ある場合 |
| BR-05 | &セレクタのフラット化 | セレクタが`&`のみのルールは子ノードを親にフラット展開する | セレクタが&の場合 |
| BR-06 | referenceの除外 | `@reference`コンテキスト内のノードは出力から除外される | contextにreferenceフラグがある場合 |
| BR-07 | AtRootの展開 | AtRootノードの子ノードは最上位レベルに展開される | AtRootノードの処理時 |
| BR-08 | @property重複除去 | 同名の@propertyルールは最初のもののみ出力される | 同名@propertyが複数ある場合 |

### 計算ロジック

- **テーマ変数の使用判定**: `isVariableUsed`関数でThemeOptions.STATICまたはUSEDフラグ、およびvariableDependenciesの依存関係チェーンを辿って使用状況を判定
- **color-mixポリフィル**: `color-mix()`内のvar()参照をテーマ値でインライン化し、フォールバック値を生成。カラースペースをsrgbに変更

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Error | cloneAstNodeで未知のノードkindが渡された | `Unknown node kind: {kind}` |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- toCss関数は位置トラッキング（track=true）時にSource.codeフィールドに結果を書き込み、ソースマップ生成に必要な位置情報を各ノードのdstフィールドに設定する
- optimizeAstはASTを1回のパスで変換し、後処理で未使用変数・キーフレームを除去する

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

特になし。

## 備考

- `rule`関数は`@`で始まるセレクタをAtRuleとして、それ以外をStyleRuleとして生成するヘルパーである
- `cssContext`関数はwalkのVisitContextをラップし、CSSコンテキスト情報（base、reference等）の遅延解決を提供する
- Context型とAtRoot型は印刷用の特殊ノードであり、toCssでは空文字列を返す（optimizeAstで事前に処理されるべき）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ast.ts | `packages/tailwindcss/src/ast.ts` | AstNode型のUnion定義（68行目）と各ノード型（13-65行目） |

**読解のコツ**: AstNodeは6種類のUnion型である。`StyleRule`と`AtRule`は`Rule`型としてもまとめられる。`Context`と`AtRoot`はTailwind CSS内部でのみ使用される特殊ノードで、最終的なCSS出力には含まれない。各ノードの`src`/`dst`フィールドはSourceLocation型でソースマップに使用される。

#### Step 2: ノード生成関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ast.ts | `packages/tailwindcss/src/ast.ts` | ファクトリ関数群（70-124行目）の生成パターン |

**主要処理フロー**:
- **70-76行目**: styleRule - セレクタ付きルールノード生成
- **78-85行目**: atRule - at-ruleノード生成
- **87-93行目**: rule - @始まりならatRule、それ以外はstyleRuleを返すヘルパー
- **95-102行目**: decl - 宣言ノード生成
- **104-109行目**: comment - コメントノード生成
- **111-117行目**: context - コンテキストノード生成
- **119-124行目**: atRoot - AtRootノード生成

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ast.ts | `packages/tailwindcss/src/ast.ts` | `optimizeAst`関数（220-680行目）。transform内部関数の再帰処理 |

**主要処理フロー**:
- **237-294行目**: Declaration処理 - テーマ変数追跡、CSS変数使用追跡、color-mix検出
- **298-338行目**: Rule処理 - 子ノード変換、重複宣言除去、&セレクタフラット化
- **341-380行目**: @property AtRule処理 - ポリフィル生成、重複除去
- **383-409行目**: その他AtRule処理 - @keyframes/color-mixコンテキスト管理
- **413-421行目**: AtRoot処理 - 最上位展開
- **424-433行目**: Context処理 - reference除外、コンテキスト継承
- **452-506行目**: 未使用テーマ変数の除去
- **509-514行目**: 未使用@keyframesの除去
- **521-617行目**: color-mixポリフィル生成
- **619-677行目**: @propertyポリフィル生成

#### Step 4: toCss関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ast.ts | `packages/tailwindcss/src/ast.ts` | `toCss`関数（682-887行目）。stringify内部関数の再帰処理とソースマップ用位置トラッキング |

**主要処理フロー**:
- **695-724行目**: Declaration のCSS文字列化（インデント、プロパティ、値、!important）
- **727-761行目**: Rule のCSS文字列化（セレクタ、子ノード再帰、インデント管理）
- **764-840行目**: AtRule のCSS文字列化（空ノード時はセミコロン終端、それ以外はブロック）
- **843-861行目**: Comment のCSS文字列化
- **866-868行目**: Context/AtRoot は空文字列（optimizeAstで処理済みの想定）

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

```
ast.ts モジュール
    |
    +-- ノード生成関数群
    |    +-- styleRule(selector, nodes)
    |    +-- atRule(name, params, nodes)
    |    +-- rule(selector, nodes)
    |    +-- decl(property, value, important)
    |    +-- comment(value)
    |    +-- context(context, nodes)
    |    +-- atRoot(nodes)
    |
    +-- cloneAstNode(node)          ... ノードのディープクローン
    |
    +-- cssContext(ctx)             ... CSSコンテキスト解決
    |
    +-- optimizeAst(ast, designSystem, polyfills)
    |    |
    |    +-- transform(node, parent, context, depth)  ... 再帰変換
    |    +-- isVariableUsed()                         ... テーマ変数使用判定
    |    +-- extractKeyframeNames()                   ... keyframe名抽出
    |
    +-- toCss(ast, track)
         |
         +-- stringify(node, depth)  ... 再帰的CSS文字列化
```

### データフロー図

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

AstNode[]         ──▶  optimizeAst            ──▶  AstNode[]（最適化済み）
                       ├─ 未使用変数除去
                       ├─ 重複宣言除去
                       ├─ ポリフィル生成
                       └─ AtRoot展開

AstNode[]         ──▶  toCss                  ──▶  CSS文字列
（最適化済み）          ├─ インデント付きCSS生成
                       └─ ソースマップ位置記録
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ast.ts | `packages/tailwindcss/src/ast.ts` | ソース | ASTノード型定義、生成関数、optimizeAst、toCss |
| css-parser.ts | `packages/tailwindcss/src/css-parser.ts` | ソース | ASTノード生成の呼び出し元（parseAtRule等） |
| walk.ts | `packages/tailwindcss/src/walk.ts` | ソース | optimizeAst内で使用されるASTウォーカー |
| theme.ts | `packages/tailwindcss/src/theme.ts` | ソース | テーマ変数の使用判定に使用 |
| design-system.ts | `packages/tailwindcss/src/design-system.ts` | ソース | optimizeAstに渡されるDesignSystem |
| value-parser.ts | `packages/tailwindcss/src/value-parser.ts` | ソース | color-mixポリフィル生成で値のパースに使用 |
| utils/default-map.ts | `packages/tailwindcss/src/utils/default-map.ts` | ソース | cssThemeVariables等の遅延初期化Map |
| utils/variables.ts | `packages/tailwindcss/src/utils/variables.ts` | ソース | extractUsedVariables関数 |
| source-maps/source.ts | `packages/tailwindcss/src/source-maps/source.ts` | ソース | Source型、SourceLocation型定義 |
