# 通知設計書 24-未知のユーティリティクラスエラー

## 概要

本ドキュメントは、Tailwind CSSの`@apply`ディレクティブにおいて、指定されたユーティリティクラスが見つからない場合のフォールバック（最終手段）エラー通知の設計を定義する。

### 本通知の処理概要

`@apply`ディレクティブで指定されたユーティリティクラスがDesignSystemで解決できず、prefix不一致、ブロックリスト登録、未知variant、テーマ未ロードのいずれにも該当しない場合に、最も汎用的なエラーメッセージを出力する通知処理である。これは`onInvalidCandidate`コールバック内の最終フォールバックエラーとして機能する。

**業務上の目的・背景**：`@apply`で指定されたユーティリティクラスが存在しない場合の原因は多岐にわたる。タイプミス、カスタムユーティリティの未定義、プラグインの未インストールなどが考えられる。先行する4つの特化エラーチェック（prefix, blocklist, variant, theme空）で原因を特定できなかった場合に、本通知が汎用的なエラーメッセージを出力して開発者に問題を報告する。

**通知の送信タイミング**：CSS生成処理における`@apply`展開フェーズで、`onInvalidCandidate`コールバック内の全ての特化チェックを通過した後、最終行（apply.ts:242行目）でエラーがthrowされる。

**通知の受信者**：CLIビルドコマンドまたはPostCSSプラグイン経由でビルドを実行した開発者。エラーはthrowされるため、ビルドツールのコンソール出力に表示される。

**通知内容の概要**：`Cannot apply unknown utility class \`{candidate}\``という簡潔なエラーメッセージが出力される。特化エラーと異なり、公式ドキュメントへのリンクや追加の提案は含まれない。

**期待されるアクション**：開発者は、ユーティリティクラス名のタイプミスを確認する。正しいクラス名であれば、カスタムユーティリティを`@utility`ディレクティブで定義するか、必要なプラグインをインストールする。

## 通知種別

ランタイムエラー（`throw new Error`）。ビルド時にCLIのstderrまたはビルドツールのエラー出力としてコンソールに表示される。

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（throwによるエラー伝播） |
| 優先度 | 高（ビルド処理を中断する致命的エラー） |
| リトライ | 無（コード修正が必要） |

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

ビルドプロセスの呼び出し元に対してエラーが伝播する。CLIの場合はプロセスのstderrに出力され、PostCSSプラグインの場合は`console.error`経由で出力された後、PostCSSのエラーとして再throwされる。

## 通知テンプレート

### メール通知の場合

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

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

### 本文テンプレート

```
Cannot apply unknown utility class `{candidate}`
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| candidate | @applyで指定されたユーティリティクラス名 | `@apply`ディレクティブのパラメータ解析結果 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ビルド処理 | `@apply`ディレクティブの展開処理 | candidateが未知であり、prefix/blocklist/variant/theme空の全特化チェックに該当しない場合 | 最終フォールバックエラー |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| candidateが有効 | candidateがDesignSystemで正常にコンパイルできる場合 |
| 先行エラーチェックに該当 | prefix(No.20)/blocklist(No.21)/variant(No.22)/theme空(No.23)のいずれかに該当した場合はそちらが優先される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A["@applyディレクティブ検出"] --> B["compileCandidates実行"]
    B --> C["onInvalidCandidate呼び出し"]
    C --> D{"prefixチェックに該当?"}
    D -->|"Yes"| E["prefixエラー（No.20）"]
    D -->|"No"| F{"blocklistチェックに該当?"}
    F -->|"Yes"| G["blocklistエラー（No.21）"]
    F -->|"No"| H{"variantチェックに該当?"}
    H -->|"Yes"| I["variantエラー（No.22）"]
    H -->|"No"| J{"theme.size === 0?"}
    J -->|"Yes"| K["@reference不足エラー（No.23）"]
    J -->|"No"| L["throw new Error（汎用未知クラスエラー）"]
    L --> M["ビルド処理中断"]
```

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

### 参照テーブル一覧

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

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

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 未知ユーティリティクラスエラー | candidateがDesignSystemで解決不可、かつ全特化チェック不該当 | クラス名のタイプミス修正、カスタムユーティリティ定義、プラグインインストール |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A（コード修正が必要） |

## 配信設定

### レート制限

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

### 配信時間帯

制限なし。ビルド実行時に即座にエラーが出力される。

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

エラーメッセージにはユーティリティクラス名のみが含まれ、個人情報やシークレットは含まれない。

## 備考

- 本エラーは`onInvalidCandidate`コールバック内の最後の`throw`文（apply.ts:242行目）であり、他の全ての特化チェックを通過した場合のフォールバックとして機能する。
- テーマが正常にロードされている状態で未知のクラスが指定された場合にのみ発生する。
- `compileCandidates`内の`invalidCandidates`チェック（compile.ts:28-30行目）でcandidateが無効と判定された後に`onInvalidCandidate`が呼ばれるが、`designSystem.parseCandidate`がcandidateをパースできない場合にも呼ばれる（compile.ts:34-36行目）。

---

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

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

### 推奨読解順序

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

candidateの解析に使用されるDesignSystemのメソッドを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | design-system.ts | `packages/tailwindcss/src/design-system.ts` | `parseCandidate`メソッド（49行目）と`invalidCandidates`（40行目）の型定義 |

**読解のコツ**: `parseCandidate`はcandidate文字列をパースしてCandidate型の配列を返す。空配列の場合はそのcandidateが無効であることを意味する。

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

`compileCandidates`関数内でcandidateが無効と判定される流れを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | compile.ts | `packages/tailwindcss/src/compile.ts` | 27-37行目の候補チェックループ。`invalidCandidates.has`（28行目）またはparseCandidate結果が空（34行目）の場合に`onInvalidCandidate`が呼ばれる |

**主要処理フロー**:
1. **28行目**: `designSystem.invalidCandidates.has(rawCandidate)` — ブロックリストチェック
2. **29行目**: `onInvalidCandidate?.(rawCandidate)` — invalidの場合コールバック
3. **33行目**: `designSystem.parseCandidate(rawCandidate)` — パース試行
4. **35行目**: `onInvalidCandidate?.(rawCandidate)` — パース失敗時コールバック

#### Step 3: フォールバックエラーを理解する

`onInvalidCandidate`コールバック内の最終フォールバック処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | apply.ts | `packages/tailwindcss/src/apply.ts` | 242行目の`throw new Error(\`Cannot apply unknown utility class \`${candidate}\`\``)`。全特化チェック通過後の最終行 |

**主要処理フロー**:
- **242行目**: `throw new Error(\`Cannot apply unknown utility class \`${candidate}\`\`)`

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

```
substituteAtApply (apply.ts:10)
    |
    +-- compileCandidates(candidates, designSystem, {...}) (apply.ts:178)
           |
           +-- onInvalidCandidate(candidate) (apply.ts:180)
                  |
                  +-- prefix チェック (apply.ts:182-186) → No.20
                  |
                  +-- invalidCandidates チェック (apply.ts:196-199) → No.21
                  |
                  +-- variant チェック (apply.ts:202-229) → No.22
                  |
                  +-- theme空チェック (apply.ts:235-239) → No.23
                  |
                  +-- throw new Error("Cannot apply unknown utility class...") (apply.ts:242)
                         ↑ 本通知（No.24）：最終フォールバック
```

### データフロー図

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

CSSファイル中の            substituteAtApply()              throw new Error
@apply unknown-cls  ───>   compileCandidates()  ───>       "Cannot apply unknown utility
                           onInvalidCandidate()             class `unknown-cls`"
                           全特化チェック不該当              ↓
                           → 最終フォールバック          ビルド処理中断
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| apply.ts | `packages/tailwindcss/src/apply.ts` | ソース | @apply展開処理。汎用未知クラスエラー（242行目） |
| compile.ts | `packages/tailwindcss/src/compile.ts` | ソース | candidateコンパイル処理。onInvalidCandidateコールバック呼び出し |
| design-system.ts | `packages/tailwindcss/src/design-system.ts` | ソース | DesignSystem型定義。parseCandidateメソッドを提供 |
