# 通知設計書 27-PostCSSプラグインエラー

## 概要

本ドキュメントは、Tailwind CSSのPostCSSプラグイン処理中にエラーが発生した場合に`console.error`でエラー内容を出力し、その後PostCSSエラーとして再throwする通知の設計を定義する。

### 本通知の処理概要

PostCSSプラグイン（`@tailwindcss/postcss`）の`Once`フック内のtry-catchブロックで、コンパイル、スキャン、CSS生成のいずれかのステップでエラーが発生した場合に、`console.error`でエラーを出力してから`root.error`でPostCSSエラーとして再throwする通知処理である。エラー時にはコンパイラキャッシュをnullに設定し、次回のビルドで完全再構築を強制する。

**業務上の目的・背景**：PostCSSプラグインとしてのTailwind CSSは、ViteやwebpackなどのビルドツールのPostCSSパイプライン内で動作する。エラーが発生した際に単純にthrowすると、一部のビルドツール（特にwatch mode）でファイル変更監視が停止してしまう場合がある。そのため、まず`console.error`でエラーを出力し（開発者にフィードバック）、その後`root.error`で正式なPostCSSエラーとして報告することで、ビルドツールが適切にエラーハンドリングできるようにしている。

**通知の送信タイミング**：PostCSSプラグインの`Once`フック内のtry-catchブロック（334-358行目）のcatchブロックでエラーがキャッチされた時点。

**通知の受信者**：ビルドを実行している開発者。`console.error`出力がstderrに表示される。また、PostCSSの`root.error`としてビルドツールにもエラーが伝播する。

**通知内容の概要**：キャッチされたエラーオブジェクト全体が`console.error`に渡される。その後、エラーオブジェクトの`message`プロパティまたはエラー全体を文字列化したものが`root.error`に渡される。

**期待されるアクション**：開発者はエラーメッセージに基づいて問題（CSS構文エラー、設定エラー、@applyエラーなど）を修正する。ファイルを保存すると、依存関係が正しく登録されていれば自動的に再ビルドが実行される。

## 通知種別

コンソールエラー出力（`console.error`）+ PostCSSエラー（`root.error`によるthrow）。

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（console.error + throw） |
| 優先度 | 高（エラー発生時の通知） |
| リトライ | 無（ただし次回ビルド時にフルリビルドが強制される） |

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

catchブロックでキャッチされた全てのエラーが対象。エラーオブジェクトに`message`プロパティが存在する場合は`error.message`がPostCSSエラーメッセージに使用され、存在しない場合はエラーオブジェクト全体が文字列化される。

## 通知テンプレート

### メール通知の場合

本通知はメール送信ではなく、コンソールエラー出力 + PostCSSエラーである。

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | N/A |
| 送信元名称 | N/A |
| 件名 | N/A |
| 形式 | テキスト（stderr出力 + PostCSSエラー） |

### 本文テンプレート

console.error出力：
```
{errorオブジェクト全体}
```

PostCSSエラー（messageプロパティがある場合）：
```
{error.message}
```

PostCSSエラー（messageプロパティがない場合）：
```
{error文字列化}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | N/A | N/A | 添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| error | キャッチされたエラーオブジェクト | try-catchのcatch節 | Yes |
| error.message | エラーメッセージ文字列 | エラーオブジェクトのmessageプロパティ | No（存在しない場合あり） |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ビルド処理 | PostCSSプラグインのOnceフック内でエラー発生 | try-catch内で例外がスローされた場合 | コンパイル/スキャン/CSS生成のいずれかでエラー発生 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| エラーが発生しない | 正常処理時はcatchブロックに到達しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A["PostCSS Onceフック try開始"] --> B["コンパイラ取得/生成"]
    B --> C["ファイル依存関係登録"]
    C --> D["スキャナー設定・候補スキャン"]
    D --> E["CSS生成・最適化"]
    E --> F["PostCSS AST更新"]
    B -.->|"エラー発生"| G["catch(error)"]
    C -.->|"エラー発生"| G
    D -.->|"エラー発生"| G
    E -.->|"エラー発生"| G
    F -.->|"エラー発生"| G
    G --> H["context.compiler = null（キャッシュクリア）"]
    H --> I["fullRebuildPathsの依存関係メッセージ再登録"]
    I --> J["console.error(error)"]
    J --> K{"errorにmessageプロパティあり?"}
    K -->|"Yes"| L["throw root.error(error.message)"]
    K -->|"No"| M["throw root.error(String(error))"]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | N/A | データベースは使用しない |

### テーブル別参照項目詳細

本通知ではデータベースを参照しない。

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| N/A | N/A | データベース更新なし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| コンパイルエラー | CSS構文エラー、設定ファイルエラーなど | CSSファイルまたは設定ファイルを修正する |
| @applyエラー | @applyで無効なクラスが参照された場合 | @applyの対象クラスを修正する |
| スキャンエラー | ファイルシステムエラーなど | ファイル権限やパスの問題を修正する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（直接的なリトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | 次回のファイル変更検知で自動的にフルリビルドが実行される |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし。PostCSSプラグイン処理時にエラーが発生した際に即座に出力される。

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

エラーオブジェクト全体が`console.error`に渡されるため、スタックトレースにファイルパスが含まれる場合がある。ビルドログが外部に公開される環境では注意が必要。

## 備考

- `context.compiler = null`（336行目）により、エラー発生後の次回ビルドでコンパイラが再生成され、フルリビルドが強制される。
- catchブロック内で`fullRebuildPaths`の依存関係を再登録している（340-347行目）。これにより、エラー発生後もファイル変更によるリビルドが正しくトリガーされる。
- コメント（349-350行目）に記載されているように、一部の状況では単純にエラーをthrowするとPostCSSの変更監視が停止するため、まず`console.error`で出力してから`root.error`でthrowするという二段階の処理が行われている。

---

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

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

### 推奨読解順序

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

PostCSSの`root.error`メソッドとcatchで捕捉されるエラーの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | 334-358行目のcatchブロック全体。エラーオブジェクトの型判定（`typeof error === 'object' && 'message' in error`）を理解する |

**読解のコツ**: `root.error()`はPostCSSの`Node`クラスのメソッドで、PostCSS固有のエラーオブジェクト（`CssSyntaxError`）を生成してthrowする。元のエラーメッセージを含む。

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

PostCSSプラグインのOnceフック内のtry-catchの範囲を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | 153-358行目のtry-catchブロック。tryブロック内の全処理（コンパイラ、スキャナー、CSS生成、最適化、AST更新）がcatchの対象 |

**主要処理フロー**:
1. **153行目**: tryブロック開始
2. **334行目**: catchブロック開始
3. **336行目**: `context.compiler = null` — コンパイラキャッシュクリア
4. **340-347行目**: fullRebuildPathsの依存関係メッセージ再登録
5. **351行目**: `console.error(error)` — エラーをstderrに出力
6. **353-354行目**: `error.message`がある場合は`root.error(error.message)`でthrow
7. **357行目**: `error.message`がない場合は`root.error(String(error))`でthrow

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

```
tailwindcss PostCSS Plugin (index.ts:71)
    |
    +-- Once(root, {result, postcss}) (index.ts:86)
           |
           +-- try { ... } (index.ts:153-333)
           |      |
           |      +-- コンパイラ取得/生成 (index.ts:156-207)
           |      +-- ファイル依存関係登録 (index.ts:165-197)
           |      +-- スキャナー設定・スキャン (index.ts:211-235)
           |      +-- CSS生成・最適化 (index.ts:287-316)
           |      +-- PostCSS AST更新 (index.ts:320-331)
           |
           +-- catch (error) { ... } (index.ts:334-358)
                  |
                  +-- context.compiler = null (index.ts:336)
                  +-- fullRebuildPaths依存関係再登録 (index.ts:340-347)
                  +-- console.error(error) (index.ts:351)
                  +-- root.error(message) (index.ts:354 or 357)
```

### データフロー図

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

Onceフック内の            catch(error)                 console.error(error)
任意のエラー       ───>   context.compiler = null ───>  → stderr出力
                          fullRebuildPaths再登録
                          error型判定                   root.error(message)
                                                        → PostCSSエラーthrow
                                                             ↓
                                                        ビルドツールに伝播
                                                        （watch mode継続可能）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts (postcss) | `packages/@tailwindcss-postcss/src/index.ts` | ソース | PostCSSプラグインのメイン処理。エラーハンドリング（334-358行目） |
