# 通知設計書 15-prefix変換不可警告

## 概要

本ドキュメントは、Tailwind CSSのupgradeツールにおいて、v3からv4へのprefix値の自動変換ができない場合に`console.warn`で警告を出力しフォールバック値を提案する通知の設計を記述する。

### 本通知の処理概要

v3からv4へのマイグレーション処理（`migratePrefixValue`関数）において、prefix値をv4互換の形式に変換する際、正規表現でv4互換の文字列を抽出できない場合に警告メッセージを出力し、フォールバック値として`"tw"`を提案・適用する処理である。

**業務上の目的・背景**：Tailwind CSS v3からv4へのアップグレード時に、prefix設定の自動変換が行われる。v4ではprefixは小文字ASCII文字（a-z）のみで構成される必要がある。v3のprefix値が数字、記号、大文字のみで構成されている場合など、有効な小文字文字列を抽出できない場合がある。この警告により、開発者に自動変換の失敗を通知し、手動でprefixを設定するよう促す。

**通知の送信タイミング**：upgradeツールの実行中に`migratePrefixValue`関数が呼び出され、VALID_PREFIX正規表現（`/([a-z]+)/`）でprefixからマッチする文字列が見つからない場合に送信される。

**通知の受信者**：upgradeツールを実行している開発者。コンソール（stderr）を通じて警告が表示される。

**通知内容の概要**：元のprefix値がv4で使用できず自動変換もできないことを通知し、フォールバック値として`"tw"`を自動適用した旨のメッセージが出力される。

**期待されるアクション**：開発者はupgradeツールの出力を確認し、自動適用された`"tw"`フォールバック値が適切でない場合は手動でTailwind CSS v4のprefix設定を調整する。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

### メール通知の場合

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

### 本文テンプレート

```
The prefix "{元のprefix値} can not be used with Tailwind CSS v4 and cannot be converted to a valid one automatically. We've updated it to "tw" for you.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| prefix | 元のv3 prefix値 | migratePrefixValue関数の引数 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| upgradeツール実行 | migratePrefixValue関数呼び出し | VALID_PREFIX正規表現にマッチしない | migrate-prefix.ts 133行目 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| VALID_PREFIX正規表現にマッチする場合 | 小文字ASCII文字が1文字以上含まれる場合は変換成功としてスキップ |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[migratePrefixValue呼び出し] --> B[prefix.toLocaleLowerCaseで小文字化]
    B --> C[VALID_PREFIX正規表現でマッチ]
    C --> D{マッチ成功?}
    D -->|Yes| E[マッチ結果を返却]
    D -->|No| F[console.warn: 変換不可警告]
    F --> G["フォールバック値 'tw' を返却"]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| prefix変換不可 | VALID_PREFIX正規表現にマッチしない | フォールバック値'tw'を使用し、手動修正を促す |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0 |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A（警告のみ。フォールバック値で処理継続） |

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（upgradeツール実行時に随時出力）

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

prefix値（短い文字列）のみが出力されるため、機密情報の漏洩リスクはない。

## 備考

- VALID_PREFIX正規表現は`/([a-z]+)/`であり、小文字ASCII文字の連続を抽出する（130行目）
- 入力文字列は`toLocaleLowerCase()`で小文字化された後に正規表現が適用される（132行目）
- フォールバック値は固定値`"tw"`（137行目）
- 正規表現にマッチする場合、最初のマッチグループ（`result[0]`）が返却される（139行目）
- 注意：警告メッセージ内にクォーテーションの閉じ忘れがあるように見える（`"{prefix}`の部分）が、これはソースコード上の実際のメッセージそのものである

---

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

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

### 推奨読解順序

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

prefix値の入出力とVALID_PREFIX正規表現を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | migrate-prefix.ts | `packages/@tailwindcss-upgrade/src/codemods/template/migrate-prefix.ts` | 130行目: VALID_PREFIX正規表現の定義 |
| 1-2 | migrate-prefix.ts | `packages/@tailwindcss-upgrade/src/codemods/template/migrate-prefix.ts` | 131行目: migratePrefixValue関数のシグネチャ |

**読解のコツ**: VALID_PREFIXは`/([a-z]+)/`であり、キャプチャグループで小文字文字列を抽出する。`exec`の返り値が`null`の場合がエラーケース。

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

migratePrefixValue関数のロジックを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | migrate-prefix.ts | `packages/@tailwindcss-upgrade/src/codemods/template/migrate-prefix.ts` | 131-140行目: migratePrefixValue関数全体 |

**主要処理フロー**:
1. **132行目**: `prefix.toLocaleLowerCase()`で入力を小文字化し、VALID_PREFIX.exec()でマッチ
2. **133行目**: resultが`null`（マッチなし）の場合の分岐
3. **134-136行目**: console.warnで変換不可の警告メッセージを出力
4. **137行目**: フォールバック値`'tw'`を返却
5. **139行目**: マッチ成功時は`result[0]`を返却

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

```
migratePrefix(designSystem, userConfig, rawCandidate) [migrate-prefix.ts:10]
    |
    +-- [prefix検証処理とは独立した呼び出し元から]
            |
            +-- migratePrefixValue(prefix) [migrate-prefix.ts:131]
                    |
                    +-- VALID_PREFIX.exec(prefix.toLocaleLowerCase()) [132行目]
                    |       |
                    |       +-- [マッチなし] console.warn() [134-136行目]
                    |       |       +-- return 'tw' [137行目]
                    |       |
                    |       +-- [マッチあり] return result[0] [139行目]
```

### データフロー図

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

v3 prefix値       --->  toLocaleLowerCase()      --->  小文字化されたprefix
  (例: "TW-")          |
                       v
                  VALID_PREFIX.exec()
                       |
                  [マッチなし]
                       |
                       v
                  console.warn()        --->  stderr: 変換不可警告
                  return 'tw'           --->  フォールバックprefix値
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| migrate-prefix.ts | `packages/@tailwindcss-upgrade/src/codemods/template/migrate-prefix.ts` | ソース | prefix値のv3->v4マイグレーション（migratePrefixValue関数） |
| version.ts | `packages/@tailwindcss-upgrade/src/utils/version.ts` | ソース | バージョン判定ユーティリティ（isMajor関数） |
