# 通知設計書 11-ビルドエラー

## 概要

本ドキュメントは、Tailwind CSS CLIのbuildコマンドにおいてCSS生成中にエラーが発生した場合に出力されるエラー通知の設計を記述する。

### 本通知の処理概要

buildコマンドの実行中にCSS生成処理でエラーが発生した際、エラーメッセージを標準エラー出力（stderr）に出力し、プロセスを異常終了させる通知処理である。

**業務上の目的・背景**：Tailwind CSSのCLIツールにおいて、CSSのコンパイル処理中に予期しないエラーが発生した場合、開発者に対して即座にエラー内容を通知する必要がある。これにより、開発者はビルド失敗の原因を特定し、CSSファイルやTailwind設定の問題を修正できる。ビルドパイプラインやCI/CDの中でエラーを検知し、不正なCSSが本番環境に配信されることを防ぐ。

**通知の送信タイミング**：buildコマンドの実行中、`handleError`関数でラップされたCSS生成処理（`compiler.build()`）がエラーをスローした場合に送信される。また、watchモード中にビルドエラーが発生した場合にもcatchブロックでエラーメッセージが出力される。

**通知の受信者**：CLIを実行している開発者。標準エラー出力（stderr）を通じてターミナルに表示される。

**通知内容の概要**：エラーオブジェクトの`toString()`メソッドにより生成されたエラーメッセージが出力される。CSSの構文エラー、ファイル読み込みエラー、コンパイルエラーなど、様々な種類のエラーが含まれ得る。

**期待されるアクション**：開発者はエラーメッセージを確認し、入力CSSファイルやTailwind CSS設定を修正する。watchモードの場合はファイルを修正して保存すると自動的にリビルドが実行される。非watchモードの場合はエラー修正後にbuildコマンドを再実行する。

## 通知種別

CLIエラー通知（標準エラー出力 / stderr）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（プロセス内直接出力） |
| 優先度 | 高 |
| リトライ | なし（非watchモード時はプロセス終了、watchモード時は次回ファイル変更時に自動リトライ） |

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

CLIプロセスの標準エラー出力（stderr）に直接出力する。送信先の動的な決定ロジックは存在しない。`eprintln`関数を通じて`process.stderr.write()`が呼び出される。

## 通知テンプレート

### メール通知の場合

該当なし（CLI標準エラー出力のみ）

### 本文テンプレート

```
{Error.toString()の出力}
```

非watchモードの場合（`handleError`関数内）:
```
{err.toString()}
```
その後、`process.exit(1)`でプロセスが異常終了する。

watchモードの場合（catchブロック内）:
```
{err.toString()}
```
プロセスは終了せず、次のファイル変更を監視し続ける。

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| err | エラーオブジェクト | compiler.build()がスローした例外 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI操作 | `handleError`内でのCSS生成エラー | errがError型インスタンスである | 初回ビルド時のエラー（77行目） |
| CLI操作 | watchモードでのCSS生成エラー | errがError型インスタンスである | watchモード中のリビルドエラー（374行目） |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| errがErrorインスタンスでない場合 | instanceof Errorチェックにより、Error型でない例外は出力されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[buildコマンド実行] --> B[CSS生成処理]
    B -->|エラー発生| C{Errorインスタンス?}
    C -->|Yes| D[eprintln でエラーメッセージ出力]
    C -->|No| E{watchモード?}
    D --> E
    E -->|No| F[process.exit 1]
    E -->|Yes| G[次のファイル変更を監視]
    B -->|成功| H[CSS出力・完了メッセージ]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| CSS構文エラー | 入力CSSに構文エラーがある場合 | CSSファイルを修正 |
| コンパイルエラー | Tailwind CSSのコンパイル処理で問題が発生した場合 | 設定ファイルや入力CSSを確認 |
| ファイルI/Oエラー | 入力ファイルの読み込みに失敗した場合 | ファイルのパス・権限を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（非watchモード）/ 無制限（watchモード - ファイル変更検知ごと） |
| リトライ間隔 | N/A（非watchモード）/ ファイル変更検知まで（watchモード） |
| リトライ対象エラー | watchモードではすべてのエラー（プロセスは終了しない） |

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（CLIコマンド実行時に随時出力）

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

エラーメッセージにはファイルパスが含まれる可能性があるが、CLIツールのローカル実行であるため、特段のセキュリティリスクはない。エラーメッセージは標準エラー出力に出力されるため、ログファイルへのリダイレクト時にはファイルパスが記録される点に留意する。

## 備考

- `handleError`関数（72-81行目）は非watchモードでの初回ビルドエラーを処理する汎用的なエラーハンドラーである
- watchモードでは370-376行目のtry-catchブロックでエラーをキャッチし、プロセスを終了させずに監視を継続する
- `eprintln`関数は`process.stderr.write()`のラッパーである

---

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

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

### 推奨読解順序

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

エラーオブジェクトの構造と、CLIのオプション定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/@tailwindcss-cli/src/commands/build/index.ts` | 30-70行目: CLIオプション定義（`--input`, `--output`, `--watch`等） |
| 1-2 | renderer.ts | `packages/@tailwindcss-cli/src/utils/renderer.ts` | 88-89行目: `eprintln`関数の定義 |

**読解のコツ**: TypeScriptの`satisfies`演算子や`Result<ReturnType<typeof options>>`のようなユーティリティ型の使用に注目。

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

buildコマンドのメインハンドラーを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/@tailwindcss-cli/src/commands/build/index.ts` | 83行目: `handle`関数がエントリーポイント |

**主要処理フロー**:
1. **72-81行目**: `handleError`関数 - try-catchでエラーをキャッチし、Error型ならeprintlnで出力後、exit(1)
2. **250行目**: `handleError(() => createCompiler(input, I))` - コンパイラ作成時のエラーハンドリング
3. **399行目**: `handleError(() => compiler.build(candidates))` - CSS生成時のエラーハンドリング

#### Step 3: watchモードのエラーハンドリングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/@tailwindcss-cli/src/commands/build/index.ts` | 370-376行目: watchモード内のtry-catchブロック |

**主要処理フロー**:
- **370行目**: catchブロック開始
- **373-374行目**: errがErrorインスタンスの場合、`eprintln(err.toString())`で出力
- **376行目**: catchブロック終了（プロセスは終了しない）

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

```
handle(args) [build/index.ts:83]
    |
    +-- handleError(fn) [build/index.ts:72]
    |       |
    |       +-- fn() -> compiler.build(candidates) [build/index.ts:399]
    |       |       |
    |       |       +-- [エラー時] eprintln(err.toString()) [build/index.ts:77]
    |       |       +-- process.exit(1) [build/index.ts:79]
    |       |
    |       +-- fn() -> createCompiler(input, I) [build/index.ts:250]
    |
    +-- [watchモード] watcher callback [build/index.ts:256]
            |
            +-- compiler.build(candidates) [build/index.ts:331,356]
            |
            +-- [エラー時] catch(err) [build/index.ts:370]
                    |
                    +-- eprintln(err.toString()) [build/index.ts:374]
```

### データフロー図

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

CSSファイル/stdin   --->  compile() + build()   --->  [成功] CSS出力
                              |                        [失敗] stderr エラーメッセージ
                              v
                         handleError() / catch
                              |
                              v
                         eprintln(err.toString())  --->  process.stderr
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/@tailwindcss-cli/src/commands/build/index.ts` | ソース | buildコマンドのメインロジック（handleError関数含む） |
| renderer.ts | `packages/@tailwindcss-cli/src/utils/renderer.ts` | ソース | eprintln等のCLI出力ユーティリティ関数 |
