# 機能設計書 30-CSS最適化（optimize）

## 概要

本ドキュメントは、Tailwind CSSにおけるCSS最適化処理（Lightning CSSによるoptimize関数）の仕様・処理フロー・内部構造を記述した機能設計書である。

### 本機能の処理概要

optimize関数は、Lightning CSSライブラリを使用してコンパイル済みCSSの最適化を行う。ネスティングの解除、メディアクエリの最適化、隣接ルールの結合、ミニファイを実行する。Lightning CSSを2回適用することで、ネスティング解除後の隣接ルール結合を確実に行い、より最適化された出力を生成する。

**業務上の目的・背景**：Tailwind CSSのコンパイラが生成するCSSは、ネストされたルールやメディアクエリを含む場合がある。本番環境向けには、これらを展開し、ブラウザ互換性を確保しつつファイルサイズを削減する必要がある。Lightning CSSは高速なRustベースのCSSツールチェーンであり、これを活用して効率的な最適化を実現する。

**機能の利用シーン**：PostCSSプラグインでのCSS出力最適化、Viteプラグインでのビルド時最適化、CLIツールでのCSS出力最適化、ミニファイ（本番ビルド時）で使用される。

**主要な処理内容**：
1. Lightning CSSのtransformを1回目実行（ネスティング解除・機能変換）
2. 警告のフィルタリング（:deep(), :slotted(), :global()の無視）
3. Lightning CSSのtransformを2回目実行（隣接ルール結合）
4. `@media not (`を`@media not all and (`に書き換え（メディアクエリrange syntax互換修正）
5. ソースマップの再マッピング（MagicString + @jridgewell/remapping）

**関連システム・外部連携**：Lightning CSS（lightningcss npmパッケージ）、MagicString（ソースマップ対応の文字列置換）、@jridgewell/remapping（ソースマップの合成）と連携する。

**権限による制御**：特になし。CSS文字列の変換処理。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | レイアウト | 補助機能 | PostCSSプラグイン内でLightning CSSによるCSS最適化が実行される |

## 機能種別

データ変換処理（CSS最適化・ミニファイ）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| input | string | Yes | 最適化対象のCSS文字列 | - |
| options.file | string | No | ファイル名（デフォルト: 'input.css'） | - |
| options.minify | boolean | No | ミニファイ有効化（デフォルト: false） | - |
| options.map | string | No | 入力ソースマップ | - |

### 入力データソース

Tailwind CSSコンパイラが生成したCSS文字列。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| code | string | 最適化されたCSS文字列 |
| map | string \| undefined | ソースマップ（入力にソースマップがある場合のみ） |

### 出力先

PostCSS/Vite/Webpack/CLIプラグインの出力として使用される。

## 処理フロー

### 処理シーケンス

```
1. Lightning CSS transform (1回目)
   ├─ ネスティング解除
   ├─ メディアクエリ最適化
   ├─ ブラウザターゲットに基づく変換
   └─ errorRecovery: trueでエラー回復
2. 警告フィルタリング
   └─ :deep()/:slotted()/:global()の擬似クラス警告を除去
3. 警告出力（テスト環境外のみ）
   └─ コード行のコンテキスト付き警告メッセージ
4. Lightning CSS transform (2回目)
   └─ 隣接ルールの結合
5. メディアクエリrange syntax修正
   └─ '@media not ('を'@media not all and ('に置換
6. ソースマップ再マッピング（必要な場合）
   └─ MagicString + remapping
```

### フローチャート

```mermaid
flowchart TD
    A[optimize開始] --> B[Lightning CSS transform 1回目]
    B --> C[警告フィルタリング]
    C --> D{警告あり?}
    D -->|Yes| E[警告出力（テスト外のみ）]
    D -->|No| F[Lightning CSS transform 2回目]
    E --> F
    F --> G["@media not (の修正"]
    G --> H{ソースマップあり?}
    H -->|Yes| I{文字列変更あり?}
    I -->|Yes| J[MagicString + remapping]
    I -->|No| K[ソースマップそのまま]
    H -->|No| L[結果を返す]
    J --> L
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 2回適用 | Lightning CSSを2回適用して、ネスティング解除後の隣接ルール結合を確実に行う | 常時 |
| BR-02 | エラー回復 | errorRecovery: trueで無効なCSSをスキップして処理を継続する | 常時 |
| BR-03 | 擬似クラス警告除去 | :deep(), :slotted(), :global()の擬似クラスに関する警告を除去する | 常時 |
| BR-04 | ブラウザターゲット | Safari 16.4, iOS Safari 16.4, Firefox 128, Chrome 111をターゲットにする | 常時 |
| BR-05 | メディアクエリ修正 | `@media not (`を`@media not all and (`に置換する | 変換後のCSS |
| BR-06 | カスタムメディア | drafts.customMediaを有効にする | 常時 |
| BR-07 | 機能選択 | Nesting + MediaQueriesをinclude、LogicalProperties + DirSelector + LightDarkをexclude | 常時 |

### 計算ロジック

ブラウザバージョンのエンコード: `(major << 16) | (minor << 8)` で数値にエンコードする。例: Safari 16.4 = `(16 << 16) | (4 << 8)`

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Warning | 無効なCSS構文（errorRecovery有効） | 警告を出力して処理を継続 |
| - | Warning | 未知の擬似クラス | :deep/:slotted/:globalの場合は無視、その他は警告出力 |

### リトライ仕様

リトライは行わない。errorRecoveryにより処理を継続する。

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

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

## パフォーマンス要件

- Lightning CSSはRustベースの高速CSS処理ライブラリ
- 2回の変換は最適化品質のため必要（ネスティング解除後の隣接ルール結合）
- MagicStringによる効率的なソースマップ対応文字列置換

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

特段のセキュリティ考慮事項はない。

## 備考

- `@tailwindcss/node`パッケージに所属する
- Lightning CSSの`Features.Nesting`と`Features.MediaQueries`を有効化し、ネスティングとメディアクエリの変換を行う
- `nonStandard.deepSelectorCombinator: true`によりVue/Angular等のフレームワーク固有セレクタをサポート
- テスト環境（NODE_ENV === 'test'）では警告を抑制する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | optimize.ts | `packages/@tailwindcss-node/src/optimize.ts` | **5-22行目**: OptimizeOptions, TransformResult型の定義 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | optimize.ts | `packages/@tailwindcss-node/src/optimize.ts` | **29-143行目**: optimize関数の全体 |

**主要処理フロー**:
1. **33-56行目**: 内部optimize関数の定義（Lightning CSS transform設定）
2. **60行目**: 1回目のtransform実行
3. **63-72行目**: 警告フィルタリング（:deep/:slotted/:globalの無視）
4. **76-113行目**: 警告出力（テスト環境外のみ）
5. **116行目**: 2回目のtransform実行
6. **123-124行目**: `@media not (`を`@media not all and (`に置換
7. **129-135行目**: ソースマップの再マッピング

#### Step 3: Lightning CSS設定の詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | optimize.ts | `packages/@tailwindcss-node/src/optimize.ts` | **34-55行目**: transform呼び出しの設定 |

**主要処理フロー**:
- **40-42行目**: drafts.customMediaとnonStandard.deepSelectorCombinatorの有効化
- **43行目**: Features.Nesting | Features.MediaQueriesをinclude
- **44行目**: Features.LogicalProperties | Features.DirSelector | Features.LightDarkをexclude
- **45-53行目**: ブラウザターゲットの設定

#### Step 4: 警告処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | optimize.ts | `packages/@tailwindcss-node/src/optimize.ts` | **63-72行目**: :deep/:slotted/:global警告のフィルタリング |
| 4-2 | optimize.ts | `packages/@tailwindcss-node/src/optimize.ts` | **76-113行目**: コンテキスト付き警告出力 |

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

```
optimize(input, options)
    │
    ├─ transform(code, settings)  -- 1回目
    │      └─ Lightning CSS (Rust)
    │
    ├─ 警告フィルタリング
    │
    ├─ transform(code, map)  -- 2回目
    │      └─ Lightning CSS (Rust)
    │
    ├─ MagicString.replaceAll('@media not (', ...)
    │
    └─ remapping([magicMap, map], ...)  -- ソースマップ合成
```

### データフロー図

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

CSS文字列              ──▶ Lightning CSS (1回目)           ──▶ TransformResult
+ OptimizeOptions            ├─ ネスティング解除               {code, map}
                             ├─ メディアクエリ最適化
                             └─ ブラウザ互換変換
                       ──▶ Lightning CSS (2回目)
                             └─ 隣接ルール結合
                       ──▶ MagicString
                             └─ @media not ( 修正
                       ──▶ remapping
                             └─ ソースマップ合成
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| optimize.ts | `packages/@tailwindcss-node/src/optimize.ts` | ソース | CSS最適化の主要実装 |
| index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | ソース | PostCSSプラグインからのoptimize呼び出し |
| index.ts (vite) | `packages/@tailwindcss-vite/src/index.ts` | ソース | Viteプラグインからのoptimize呼び出し |
| index.ts (cli) | `packages/@tailwindcss-cli/src/index.ts` | ソース | CLIからのoptimize呼び出し |
