# バッチ設計書 9-@tailwindcss/upgrade

## 概要

本ドキュメントは、Tailwind CSSプロジェクトにおけるマイグレーションバッチ `@tailwindcss/upgrade` のバッチ設計書である。Tailwind CSS v3からv4へのマイグレーションを自動実行し、CSS・テンプレート・JS設定ファイル・PostCSS設定を一括変換する処理の仕様を定義する。

### 本バッチの処理概要

本バッチは、Tailwind CSS v3で構築されたプロジェクトをv4の構文・設定形式に自動的にマイグレーションする包括的なアップグレードツールである。CSS、テンプレートファイル、JavaScript設定ファイル、PostCSS設定のすべてを対象に変換処理を行う。

**業務上の目的・背景**：Tailwind CSS v4はv3から大幅なアーキテクチャ変更があり、CSS-first設定への移行、新しいユーティリティ構文の導入、PostCSS統合の変更などが含まれる。手動でのマイグレーションは複雑で時間がかかるため、本バッチにより自動的にプロジェクト全体をv4互換形式に変換し、マイグレーションの負担を軽減する。

**バッチの実行タイミング**：ユーザーがTailwind CSSをv3からv4にアップグレードする際に手動で実行する。`npx @tailwindcss/upgrade` コマンドで起動される。

**主要な処理内容**：
1. Gitリポジトリの状態確認（クリーンでない場合は警告/エラー）
2. インストール済みTailwind CSSバージョンの確認とバージョン不一致の検出
3. CSSファイルの発見と解析（プロジェクト内の全CSSファイル）
4. スタイルシートの分析と設定ファイルへのリンク
5. JavaScript設定ファイルのマイグレーション（tailwind.config.js -> CSS-first設定）
6. CSSスタイルシートのマイグレーション（v3構文 -> v4構文）
7. スタイルシートの分割処理（必要に応じて）
8. テンプレートファイルのマイグレーション（クラス名の更新）
9. PostCSS設定のマイグレーション
10. 依存パッケージの更新（tailwindcss, @tailwindcss/cli等を最新版に）

**前後の処理との関連**：独立したツールとして動作する。実行前にはユーザーが `npm install` で依存関係を解決済みである必要がある。実行後はユーザーによる変更内容の確認とgitコミットが期待される。

**影響範囲**：プロジェクト内の全CSSファイル、テンプレートファイル（HTML/JSX/TSX等）、JavaScript設定ファイル、PostCSS設定ファイル、package.jsonの依存関係が変更される可能性がある。

## バッチ種別

マイグレーション / コード変換

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（バージョンアップ時に1回） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動実行（`npx @tailwindcss/upgrade`） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Gitリポジトリ | プロジェクトがGitで管理されていること（--forceで回避可能） |
| Gitクリーン状態 | 未コミットの変更がないこと（--forceで回避可能） |
| Tailwind CSS v3インストール済み | v3がnode_modulesにインストールされていること |
| バージョン一致 | package.jsonの指定バージョンとnode_modulesのバージョンが一致していること |
| Node.js実行環境 | Node.jsが実行可能であること |

### 実行可否判定

- Gitリポジトリがダーティな場合は `--force` フラグがない限りエラー終了する
- package.jsonのバージョンとnode_modulesのバージョンが不一致の場合はエラー終了する

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --config (-c) | string | No | なし | 設定ファイルのパス |
| --help (-h) | boolean | No | false | ヘルプの表示 |
| --force (-f) | boolean | No | false | 強制実行（Gitダーティでも続行） |
| --version (-v) | boolean | No | false | バージョン番号の表示 |
| 位置引数 | string[] | No | なし | マイグレーション対象のCSSファイルパス |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| プロジェクト内CSSファイル | CSS | マイグレーション対象のスタイルシート |
| tailwind.config.js | JavaScript | v3設定ファイル（マイグレーション対象） |
| テンプレートファイル | HTML/JSX/TSX等 | クラス名をマイグレーションする対象 |
| postcss.config.js | JavaScript | PostCSS設定ファイル（マイグレーション対象） |
| package.json | JSON | 依存パッケージの情報 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| CSSファイル | CSS | v4形式にマイグレーションされたスタイルシート |
| テンプレートファイル | HTML/JSX/TSX等 | クラス名が更新されたテンプレート |
| package.json | JSON | 依存パッケージがv4に更新された設定 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 入力と同名（上書き） |
| 出力先 | 入力と同じディレクトリ |
| 文字コード | UTF-8 |
| フォーマット | PostCSSによる整形済みCSS |

## 処理フロー

### 処理シーケンス

```
1. 初期化
   └─ ヘッダー表示、引数解析
2. Git状態確認
   └─ Gitリポジトリのダーティチェック（--force時はスキップ）
3. バージョン確認
   └─ インストール済みTailwind CSSのバージョンとpackage.jsonの整合性を検証
4. CSSファイル発見
   └─ 引数で指定されたファイル、またはglobbyで**/*.cssをスキャン（node_modules除外）
5. スタイルシート解析
   └─ 全CSSファイルを読み込み、Tailwindルートを検出
6. 設定ファイルリンク（v3マイグレーション時）
   └─ スタイルシートとtailwind.config.jsを紐付け
7. JavaScript設定マイグレーション
   └─ tailwind.config.jsの内容をCSS-first設定に変換
8. CSSスタイルシートマイグレーション
   └─ v3構文をv4構文に変換（並列処理）
9. スタイルシート分割（v3マイグレーション時）
   └─ 必要に応じてCSSファイルを分割
10. ノード整形
    └─ PostCSSでソートとフォーマット
11. ファイル書き出し
    └─ マイグレーション済みCSSをディスクに書き込み
12. 依存パッケージ更新
    └─ tailwindcss, @tailwindcss/cli等を@latestに更新
13. テンプレートマイグレーション
    └─ ソースファイル内のTailwindクラス名を更新
14. PostCSS設定マイグレーション（v3マイグレーション時）
    └─ PostCSS設定をv4互換に変換
15. クリーンアップ
    └─ 完全にマイグレーション済みの旧設定ファイルを削除
16. 結果通知
    └─ 変更の有無を表示
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{Gitクリーン?}
    B -->|いいえ and --force なし| C[エラー終了]
    B -->|はい or --force| D[バージョン確認]
    D --> E{バージョン一致?}
    E -->|いいえ| F[エラー終了]
    E -->|はい| G[CSSファイル発見・解析]
    G --> H[JS設定マイグレーション]
    H --> I[CSSマイグレーション]
    I --> J[スタイルシート分割]
    J --> K[フォーマットして書き出し]
    K --> L[依存パッケージ更新]
    L --> M[テンプレートマイグレーション]
    M --> N[PostCSS設定マイグレーション]
    N --> O[クリーンアップ・結果通知]
    O --> P[バッチ終了]
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチではデータベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Gitダーティ | Gitリポジトリに未コミットの変更がある場合 | 変更をコミットまたはスタッシュしてから再実行、または--forceを使用 |
| - | バージョン不一致 | package.jsonとnode_modulesのバージョンが異なる | npm/pnpm installを実行してから再実行 |
| - | CSS解析エラー | CSSファイルの構文エラー | エラーメッセージで対象ファイルを確認し、構文を修正 |
| - | 設定マイグレーションエラー | 設定ファイルの解析に失敗 | エラーメッセージを確認し、設定ファイルを手動で修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

マイグレーション失敗時は、gitで全変更を元に戻し（`git checkout .`）、エラーの原因を特定した上で再実行する。個別のファイルでエラーが発生した場合でも、他のファイルの処理は継続される（Promise.allSettledを使用）。

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（ファイルシステム操作のため） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A（gitによるロールバックが可能） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | プロジェクト内のCSS・テンプレートファイル数に依存 |
| 目標処理時間 | 特に定めなし（プロジェクト規模に依存） |
| メモリ使用量上限 | 特に定めなし |

## 排他制御

手動実行の1回限りのマイグレーションツールであるため、同時実行は想定しない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ヘッダー | バッチ開始時 | Tailwind CSSのバージョン情報（stderr） |
| 情報ログ | 各処理段階 | "Searching for CSS files...", "Migrating stylesheets...", "Migrating templates..."等（stderr） |
| 成功ログ | 各ファイル処理完了時 | "Migrated stylesheet: {path}", "Migrated configuration file: {path}"等（stderr） |
| エラーログ | エラー発生時 | エラーメッセージ（stderr） |
| 完了ログ | バッチ終了時 | "Verify the changes and commit them to your repository." または "No changes were made."（stderr） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 特に定めなし | - | - |

## 備考

- `npx @tailwindcss/upgrade` で実行される
- v3からv4へのマイグレーション時のみ有効な処理がある（スタイルシート分割、PostCSS設定マイグレーション、設定ファイルリンク）
- CSSファイルの並列処理には `Promise.all` が使用され、個別ファイルのエラーは `Promise.allSettled` で処理される
- マイグレーション対象の依存パッケージ：tailwindcss, @tailwindcss/cli, @tailwindcss/postcss, @tailwindcss/vite, @tailwindcss/node, @tailwindcss/oxide, prettier-plugin-tailwindcss
- 完全にマイグレーション済みのJS設定ファイルは自動削除される（cleanupで `fs.rm`）
- テンプレートマイグレーションでは `@tailwindcss/oxide` の `Scanner` を使用してソースファイルを検出する
- `sortBuckets()` と `formatNodes()` のPostCSSプラグインでCSS出力が整形される
