# 通知設計書 31-CSS最適化プロセス警告

## 概要

本ドキュメントは、Tailwind CSSの出力CSS最適化処理（Lightning CSS使用）中に発生した警告をコンソールに出力する通知機能の設計書である。

### 本通知の処理概要

CSS最適化プロセスにおいて、`errorRecovery: true` オプションにより回復可能なエラーが検出された場合に、ユーザーに対して警告情報をコンソール標準エラー出力（`console.warn`）を通じて通知する。警告にはCSS上の問題箇所のスニペットと行・列情報が含まれ、問題の特定を支援する。

**業務上の目的・背景**：Tailwind CSSのビルドパイプラインでは、生成されたCSSをLightning CSSライブラリを使って最適化（ネスティング展開、メディアクエリ変換、ベンダープレフィックス追加、ミニファイなど）する。この最適化処理では `errorRecovery: true` を指定することで、軽微な構文問題があってもビルドを停止せずに続行できるが、ユーザーはその問題を認識する必要がある。本通知は、そうした警告をユーザーに見える形で出力し、生成CSSの品質問題を早期に発見できるようにすることを目的としている。

**通知の送信タイミング**：`optimize` 関数内でLightning CSSの `transform` 関数を最初に実行した直後、返却された `result.warnings` 配列に要素が存在し、かつ `process.env.NODE_ENV !== 'test'`（テスト環境でない）場合に出力される。なお、Vue.jsフレームワーク固有の疑似クラス（`:deep()`, `:slotted()`, `:global()`）に関する警告はフィルタリングされ、出力対象から除外される。

**通知の受信者**：CLI・PostCSSプラグイン・Viteプラグインを通じてTailwind CSSのビルドを実行している開発者。コンソール標準エラー出力を通じて受信する。

**通知内容の概要**：警告の件数サマリー、各警告の詳細情報（問題のある行のコードスニペット、行番号・列番号、警告メッセージ）がフォーマットされて出力される。複数の警告がある場合は `Issue #1`, `Issue #2` のように番号付きで出力される。コードスニペットは問題行の前後2行のコンテキストを含み、問題箇所にはキャレット記号（`^--`）による視覚的なポインタが付与される。

**期待されるアクション**：開発者は警告内容を確認し、生成元のCSSやTailwindの設定を修正して問題を解消する。ただし、回復可能なエラーであるためビルド自体は続行されており、即座の対応は必須ではない。

## 通知種別

コンソール警告（`console.warn` による標準エラー出力）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 低 |
| リトライ | なし |

### 送信先決定ロジック

コンソール標準エラー出力に直接書き込むため、送信先の動的決定は行われない。`console.warn` を通じてNode.jsプロセスの標準エラーストリーム（stderr）に出力される。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr（`console.warn`） |
| 形式 | テキスト（ANSIカラーコード付き） |

### 本文テンプレート

```
Found {warnings.length} {warning|warnings} while optimizing generated CSS:

Issue #{idx + 1}:
│ {context line -2}
│ {context line -1}
│ {問題行}
┆         ^-- {警告メッセージ}
┆
│ {context line +1}
│ {context line +2}

```

### 添付ファイル

該当なし（コンソール出力のため添付ファイルは存在しない）

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| `result.warnings.length` | 警告の総件数 | Lightning CSS `transform` の返却値 | Yes |
| `warning.message` | 各警告のメッセージ文字列 | Lightning CSS `TransformResult.warnings[].message` | Yes |
| `warning.loc.line` | 警告の発生行番号 | Lightning CSS `TransformResult.warnings[].loc.line` | Yes |
| `warning.loc.column` | 警告の発生列番号 | Lightning CSS `TransformResult.warnings[].loc.column` | Yes |
| `input` | 最適化対象のCSS文字列（スニペット生成用） | `optimize` 関数の引数 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ビルド処理 | CLIの `build` コマンドで `--optimize` または `--minify` オプション使用時 | Lightning CSSの `transform` 結果に警告が含まれること | `@tailwindcss-cli/src/commands/build/index.ts` 経由で `optimize` 関数が呼び出される |
| ビルド処理 | PostCSSプラグインで `optimize` オプションが有効な場合 | 同上 | `@tailwindcss-postcss/src/index.ts` 経由で `optimize` 関数が呼び出される |
| ビルド処理 | Viteプラグインのビルドモードで最適化が有効な場合 | 同上 | `@tailwindcss-vite/src/index.ts` 経由で `optimize` 関数が呼び出される |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `process.env.NODE_ENV === 'test'` | テスト環境では警告出力を抑止する |
| `result.warnings.length === 0` | 警告が存在しない場合は出力しない |
| 疑似クラス `:deep()`, `:slotted()`, `:global()` に関する警告 | Vue.jsフレームワーク固有の疑似クラスは標準CSSではないが一般的に使用されるため、フィルタリングで除外される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[optimize関数呼び出し] --> B[Lightning CSS transform 1回目実行]
    B --> C[warnings フィルタリング]
    C --> D{フィルタリング後の warnings が存在するか}
    D -->|存在しない| E[警告出力スキップ]
    D -->|存在する| F{NODE_ENV === test か}
    F -->|Yes| E
    F -->|No| G[警告メッセージ構築]
    G --> H[各警告のコードスニペット生成]
    H --> I[console.warn で出力]
    I --> J[Lightning CSS transform 2回目実行]
    E --> J
    J --> K[最適化結果を返却]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（データベースは使用しない）

### 更新テーブル一覧

該当なし（データベースは使用しない）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 警告出力自体の失敗 | `console.warn` の呼び出し失敗（通常発生しない） | 特別なエラー処理はなし。最適化処理自体は継続される |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし（ビルド単位で出力） |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（ビルド実行時に随時出力）

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

- 出力される情報はCSS構文の警告のみであり、個人情報やシークレット情報は含まれない
- コードスニペットに機密情報が含まれる可能性は低いが、カスタムCSSの内容が出力されるため、CIログの公開設定には注意が必要

## 備考

- Lightning CSSは2回連続で実行されるが、警告チェックは1回目の実行結果に対してのみ行われる
- `errorRecovery: true` 設定により、構文エラーがあってもビルドが停止せず警告として報告される
- ANSIカラーコードが使用されるため、ターミナル以外の出力先では文字化けする可能性がある
- `dim` 関数（ANSI dim）と `yellow` 関数（ANSI yellow）によりコードスニペットの視覚的な区別が提供される

---

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

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

### 推奨読解順序

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

Lightning CSSの `transform` 関数が返す結果オブジェクトの `warnings` 配列がこの通知の中核データである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | optimize.ts | `packages/@tailwindcss-node/src/optimize.ts` | `OptimizeOptions` インターフェース（5-22行目）と `TransformResult` インターフェース（24-27行目）を確認し、入出力のデータ構造を理解する |

**読解のコツ**: `transform` 関数はLightning CSSライブラリが提供する外部関数であり、戻り値の `warnings` 配列には `message`, `loc.line`, `loc.column` プロパティを持つオブジェクトが含まれる。

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

`optimize` 関数本体が通知のエントリーポイントである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | optimize.ts | `packages/@tailwindcss-node/src/optimize.ts` | `optimize` 関数（29-143行目）全体の処理フローを理解する。特に60-114行目の警告処理部分が本通知の核心 |

**主要処理フロー**:
1. **34-56行目**: 内部の `optimize` 関数でLightning CSSの `transform` を呼び出す（`errorRecovery: true` 指定）
2. **60行目**: 1回目のtransform実行
3. **63-72行目**: Vue.js関連疑似クラスの警告をフィルタリング
4. **76行目**: `NODE_ENV !== 'test'` かつ `warnings.length > 0` の条件判定
5. **77-80行目**: 入力CSSを行分割し、サマリーメッセージを生成
6. **83-109行目**: 各警告についてコードスニペットを生成（前後2行のコンテキスト、キャレットポインタ付き）
7. **113行目**: `console.warn` で結合済み出力を表示

#### Step 3: 呼び出し元を理解する

`optimize` 関数は3つの異なるパッケージから呼び出される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | build/index.ts | `packages/@tailwindcss-cli/src/commands/build/index.ts` | 161行目: CLIの `build` コマンドから `--optimize` / `--minify` オプション使用時に呼び出される |
| 3-2 | index.ts | `packages/@tailwindcss-postcss/src/index.ts` | 300行目: PostCSSプラグインの `optimize` オプション有効時に `optimizeCss` として呼び出される |
| 3-3 | index.ts | `packages/@tailwindcss-vite/src/index.ts` | 283行目: Viteプラグインのビルドモードで最適化が有効な場合に呼び出される |

#### Step 4: ヘルパー関数を理解する

ANSIカラー出力のためのヘルパー関数がファイル末尾に定義されている。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | optimize.ts | `packages/@tailwindcss-node/src/optimize.ts` | `dim` 関数（145-147行目）と `yellow` 関数（149-151行目）によるANSIエスケープコードの適用方法 |

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

```
@tailwindcss-cli/build (build/index.ts:161)
    |
    +---> optimize (optimize.ts:29)
              |
              +---> transform (lightningcss) [1回目: 60行目]
              |         |
              |         +---> warnings フィルタリング (63-72行目)
              |         |
              |         +---> console.warn 出力 (76-113行目)
              |                   |
              |                   +---> dim() (145行目)
              |                   +---> yellow() (149行目)
              |
              +---> transform (lightningcss) [2回目: 116行目]

@tailwindcss-postcss (index.ts:300)
    |
    +---> optimizeCss (= optimize)
              +---> [同上]

@tailwindcss-vite (index.ts:283)
    |
    +---> optimize
              +---> [同上]
```

### データフロー図

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

CSS文字列 (input) ──────> Lightning CSS transform() ──────> TransformResult
                           (errorRecovery: true)                |
                                                                |
                                                          warnings 配列
                                                                |
                                                          フィルタリング
                                                          (Vue疑似クラス除外)
                                                                |
                                                          ┌─ NODE_ENV !== 'test'
                                                          │  かつ warnings > 0
                                                          │
                                                          v
                                                    コードスニペット生成 ──> console.warn
                                                    (行番号・列・メッセージ)    (stderr)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| optimize.ts | `packages/@tailwindcss-node/src/optimize.ts` | ソース | CSS最適化処理と警告出力のメインロジック |
| index.ts | `packages/@tailwindcss-node/src/index.ts` | ソース | `optimize` 関数のre-export |
| index.cts | `packages/@tailwindcss-node/src/index.cts` | ソース | `optimize` 関数のCJS向けre-export |
| build/index.ts | `packages/@tailwindcss-cli/src/commands/build/index.ts` | ソース | CLIビルドコマンドからの `optimize` 呼び出し元 |
| index.ts | `packages/@tailwindcss-postcss/src/index.ts` | ソース | PostCSSプラグインからの `optimize` 呼び出し元 |
| index.ts | `packages/@tailwindcss-vite/src/index.ts` | ソース | Viteプラグインからの `optimize` 呼び出し元 |
