# 通知設計書 12-サポート外bare valueデータ型警告

## 概要

本ドキュメントは、Tailwind CSSのユーティリティクラス定義において、サポートされていないbare valueデータ型が使用された場合に`console.warn`で警告を出力する通知の設計を記述する。

### 本通知の処理概要

ユーティリティクラスの定義（`@utility`ディレクティブ等）の解析中に、サポートされていないbare valueデータ型が検出された場合に、警告メッセージとコードスニペットを標準エラー出力に出力する処理である。

**業務上の目的・背景**：Tailwind CSSのユーティリティ定義では、`number`、`percentage`、`ratio`などの定義済みデータ型のみがbare value（裸の値）として使用できる。開発者が未定義のデータ型を使用した場合、意図しない動作を防ぐために警告を発する必要がある。これにより、設定ミスやタイポの早期検出が可能になる。

**通知の送信タイミング**：CSSコンパイル処理中にユーティリティ定義の値パーサー（ValueParser）がノードを走査する際、`word`ノードの値が`BARE_VALUE_DATA_TYPES`配列に含まれず、かつ任意値（`[...]`形式）でもない場合に送信される。

**通知の受信者**：Tailwind CSSを使用してCSSをビルドしている開発者。コンソール（stderr）を通じて警告が表示される。

**通知内容の概要**：サポートされないデータ型名、有効なデータ型の一覧、およびCSSコードスニペット（問題箇所のアンダーライン付き）が出力される。

**期待されるアクション**：開発者はユーティリティ定義のデータ型を有効な型（`BARE_VALUE_DATA_TYPES`に定義されたもの）に変更するか、任意値（`[...]`）形式を使用する。

## 通知種別

コンソール警告（console.warn / stderr）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（console.warn による即時出力） |
| 優先度 | 中 |
| リトライ | なし |

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

`console.warn`による標準エラー出力への直接出力。動的な送信先決定ロジックは存在しない。

## 通知テンプレート

### メール通知の場合

該当なし（コンソール警告のみ）

### 本文テンプレート

1回目の警告メッセージ:
```
Unsupported bare value data type: "{dataType}".
Only valid data types are: {BARE_VALUE_DATA_TYPES のカンマ区切り一覧}.
```

2回目の警告メッセージ（コードスニペット）:
```
```css
{fn の CSS表現}
{問題箇所のアンダーライン（^記号）}
```
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| node.value | サポートされないデータ型名 | ValueParser のノード値 | Yes |
| BARE_VALUE_DATA_TYPES | サポートされるデータ型の一覧 | utilities.ts 内の定数 | Yes |
| fn | 問題のあるCSS関数ノード | ValueParser の解析結果 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コンパイル処理 | ユーティリティ定義の値解析 | node.kind === 'word' かつ node.value が BARE_VALUE_DATA_TYPES に含まれない、かつ任意値形式でない | utilities.ts 6098-6125行目 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 任意値形式（`[...]`）の場合 | node.value が `[` で始まり `]` で終わる場合はスキップ（6100行目） |
| BARE_VALUE_DATA_TYPES に含まれる場合 | 有効なデータ型の場合はスキップ（6101行目） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーティリティ定義の値解析] --> B{node.kind === 'word'?}
    B -->|No| Z[スキップ]
    B -->|Yes| C{任意値形式?}
    C -->|Yes| Z
    C -->|No| D{BARE_VALUE_DATA_TYPESに含まれる?}
    D -->|Yes| Z
    D -->|No| E[console.warn: データ型エラーメッセージ]
    E --> F[コードスニペット生成]
    F --> G[console.warn: コードスニペット出力]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| サポート外データ型 | 無効なbare valueデータ型が使用された場合 | 有効なデータ型に変更するか任意値形式を使用 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0 |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A（警告のみでプロセスは継続） |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし（検出されたすべての違反に対して出力） |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（CSSコンパイル時に随時出力）

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

CSSのデータ型名のみが出力されるため、機密情報の漏洩リスクはない。

## 備考

- この警告はプロセスを終了させない（警告のみ）
- コードスニペットには問題のあるデータ型の位置を示すアンダーライン（`^`記号）が含まれる
- TODO コメントにあるように、将来的にはノードのソースロケーション追跡が改善される予定
- `structuredClone`を使用してCSSノードのコピーを作成し、問題箇所の特定に使用している

---

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

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

### 推奨読解順序

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

ValueParserのノード構造とBARE_VALUE_DATA_TYPESの定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | BARE_VALUE_DATA_TYPES定数の定義を確認 |
| 1-2 | value-parser.ts | `packages/tailwindcss/src/value-parser.ts` | ValueParserのノード型（kind: 'word'等）の定義 |

**読解のコツ**: `walk`関数によるAST走査パターンを理解することが重要。ノードのkindプロパティとvalueプロパティがフィルタリングに使用される。

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

ユーティリティ定義の解析処理のフローを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | 6090-6130行目: ユーティリティ定義内の値パース処理 |

**主要処理フロー**:
1. **6091-6095行目**: テーマキーの追跡（`--`で始まるwordノード）
2. **6097-6101行目**: bare valueデータ型の検証条件
3. **6103-6104行目**: console.warnで「Unsupported bare value data type」メッセージ出力
4. **6108-6117行目**: 問題箇所特定のためのコードスニペット生成
5. **6118-6124行目**: アンダーライン付きコードスニペットの出力

#### Step 3: コードスニペット生成ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | utilities.ts | `packages/tailwindcss/src/utilities.ts` | 6108-6124行目: structuredCloneとセンチネル値を使った位置特定 |

**主要処理フロー**:
- **6108行目**: 問題のデータ型名を変数に保持
- **6109行目**: 関数ノードのディープコピーを作成
- **6110行目**: センチネル値（`¶`）を設定
- **6111-6115行目**: walkでコピー内のデータ型ノードをセンチネル値に置換
- **6116行目**: アンダーライン文字列を生成
- **6117行目**: センチネル値の位置（オフセット）を計算
- **6118-6124行目**: CSSコードブロックとアンダーラインの出力

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

```
utilities.ts (ユーティリティ定義解析)
    |
    +-- walk(declarationValueAst) [ValueParser ASTの走査]
            |
            +-- node.kind === 'word' チェック [6098行目]
            |       |
            |       +-- 任意値チェック [6100行目]
            |       +-- BARE_VALUE_DATA_TYPES チェック [6101行目]
            |
            +-- console.warn(メッセージ) [6103行目]
            |
            +-- structuredClone(fn) [6109行目]
            +-- walk(copy.nodes) [6111行目] -> センチネル値置換
            +-- ValueParser.toCss() [6116-6120行目]
            +-- console.warn(コードスニペット) [6124行目]
```

### データフロー図

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

@utility定義       --->  ValueParser.parse()     --->  AST ノード
   のCSS値               |
                         v
                    walk(nodes)
                         |
                         v
                    データ型検証
                    (BARE_VALUE_DATA_TYPES)
                         |
                    [不正な場合]
                         |
                         v
                    console.warn()       --->  stderr: エラーメッセージ
                    console.warn()       --->  stderr: コードスニペット
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| utilities.ts | `packages/tailwindcss/src/utilities.ts` | ソース | ユーティリティ定義の解析・bare valueデータ型検証ロジック |
| value-parser.ts | `packages/tailwindcss/src/value-parser.ts` | ソース | CSS値のパーサー（ASTノード生成） |
| walk.ts | `packages/tailwindcss/src/walk.ts` | ソース | AST走査ユーティリティ（walk関数、WalkAction） |
