# 通知設計書 5-アップグレード完了メッセージ

## 概要

本ドキュメントは、Tailwind CSS upgradeコマンド（`@tailwindcss/upgrade`）の各処理ステップが成功した際に出力される完了メッセージ群の通知仕様を定義する。

### 本通知の処理概要

upgradeコマンドの各マイグレーション処理ステップ（設定ファイル移行、スタイルシート移行、パッケージ更新、テンプレート移行、最終結果）が正常に完了した際に、成功を示す緑色装飾付きメッセージを標準エラー出力に出力する通知処理である。

**業務上の目的・背景**：upgradeコマンドは多段階のマイグレーション処理を逐次実行する。各ステップの完了を逐次通知することで、ユーザーはアップグレードの進捗状況をリアルタイムに把握できる。これにより、処理が正常に進行していることの確認と、問題発生時のデバッグが容易になる。

**通知の送信タイミング**：以下の各ステップが成功した際に送信される。
1. JS設定ファイルのマイグレーション完了時（行172）
2. スタイルシートの書き込み完了時（行256）
3. パッケージ更新完了時（行275、各パッケージごと）
4. テンプレートマイグレーション完了時（行330, 335）
5. 最終結果通知：リポジトリに変更があった場合（行356）、変更がなかった場合（行358）

**通知の受信者**：CLIを実行した開発者。標準エラー出力（stderr）に出力される。

**通知内容の概要**：各ステップの処理対象ファイル名や処理結果を含む成功メッセージが出力される。最終ステップでは「Verify the changes and commit them」または「No changes were made」のメッセージが表示される。

**期待されるアクション**：各ステップの完了メッセージでは特にアクションは不要。最終結果通知では、変更があった場合はユーザーが変更内容を確認してコミットすることが期待される。

## 通知種別

CLI標準エラー出力（stderr）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（プロセス内直接出力） |
| 優先度 | 低（情報通知、プロセスは継続） |
| リトライ | 無し（即時出力） |

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

CLIを実行したプロセスの標準エラー出力（`process.stderr`）に対して `eprintln()` 関数経由で出力する。

## 通知テンプレート

### メール通知の場合

該当なし（CLI出力のみ）

### 本文テンプレート

**JS設定ファイルマイグレーション完了（行172-176）**:
```
│ ↳ Migrated configuration file: `{configFilePath}`
```

**スタイルシート書き込み完了（行256）**:
```
│ ↳ Migrated stylesheet: `{stylesheetPath}`
```

**パッケージ更新完了（行275）**:
```
│ ↳ Updated package: `{packageName}`
```

**テンプレートマイグレーション完了 - 設定ファイル有り（行330-333）**:
```
│ ↳ Migrated templates for configuration file: `{configFilePath}`
```

**テンプレートマイグレーション完了 - 設定ファイル無し（行335-341）**:
```
│ ↳ Migrated templates for: `{stylesheetPath}`
```

**最終結果通知 - 変更あり（行356）**:
```
│ Verify the changes and commit them to your repository.
```

**最終結果通知 - 変更なし（行358）**:
```
│ No changes were made to your repository.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| configFilePath | JS設定ファイルの相対パス | `relative(config.configFilePath, base)` | Yes（設定ファイル関連通知のみ） |
| stylesheetPath | CSSスタイルシートの相対パス | `relative(sheet.file, base)` | Yes（スタイルシート関連通知のみ） |
| packageName | 更新されたパッケージ名 | パッケージ名文字列（例: `tailwindcss`, `@tailwindcss/cli`） | Yes（パッケージ更新通知のみ） |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 内部処理 | JS設定マイグレーション成功 | `jsConfigMigration !== null` | JS設定ファイルの完全マイグレーション時 |
| 内部処理 | スタイルシート書き込み成功 | `sheet.isTailwindRoot` | Tailwindルートシートのみ |
| 内部処理 | パッケージ更新成功 | `pkgManager.add()` 成功 | 各パッケージの更新成功時 |
| 内部処理 | テンプレートマイグレーション成功 | テンプレート処理完了 | テンプレートファイルの移行完了時 |
| 内部処理 | 全処理完了 | `isRepoDirty()` の結果 | 変更有無に応じたメッセージ |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| JS設定ファイルが完全移行されなかった場合 | `jsConfigMigration` が `null` の場合、設定ファイルマイグレーション完了メッセージは出力されない |
| Tailwindルートでないスタイルシート | `sheet.isTailwindRoot` が `false` のスタイルシートは完了メッセージの対象外 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[アップグレード処理開始] --> B[JS設定ファイルマイグレーション]
    B --> C{マイグレーション成功?}
    C -->|成功| D[success: Migrated configuration file]
    C -->|スキップ| E[次のステップへ]
    D --> F[スタイルシートマイグレーション]
    E --> F
    F --> G[スタイルシート書き込み]
    G --> H{TailwindRoot?}
    H -->|Yes| I[success: Migrated stylesheet]
    H -->|No| J[次のシートへ]
    I --> K[パッケージ更新]
    J --> K
    K --> L[success: Updated package x N]
    L --> M[テンプレートマイグレーション]
    M --> N[success: Migrated templates]
    N --> O{リポジトリに変更あり?}
    O -->|あり| P[success: Verify the changes...]
    O -->|なし| Q[success: No changes were made...]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | - | 本通知は成功時のみ出力されるため、エラーケースは存在しない。エラー時は別の通知（No.6）で対応 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（CLI実行時に即時出力）

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

本通知にはファイルパスが含まれるが、これはユーザーのプロジェクト内の相対パスであり、`relative()` 関数で変換される。機密情報は含まれない。

## 備考

- 全ての完了メッセージは `renderer.ts` の `success()` 関数で緑色装飾される
- ファイルパスは `highlight()` 関数で青色のバッククォート付き装飾される
- ステップ間の情報メッセージ（「Migrating JavaScript configuration files...」「Migrating stylesheets...」等）は別の `info()` 呼び出しで行われ、本通知の範囲外
- 最終結果通知では `isRepoDirty()` を再利用してリポジトリの変更有無を判定する

---

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

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

### 推奨読解順序

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

成功メッセージの出力に使用されるデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | renderer.ts | `packages/@tailwindcss-upgrade/src/utils/renderer.ts` | `success()` 関数が `log()` を緑色パイプ（`pc.green('│')`）で呼び出す仕組みを理解する |
| 1-2 | stylesheet.ts | `packages/@tailwindcss-upgrade/src/stylesheet.ts` | `Stylesheet` クラスの `file`, `isTailwindRoot` プロパティを確認する |

**読解のコツ**: `success()` 関数は行108-110で定義されており、`art` パラメータに `pc.green('│')` を指定して `log()` を呼び出す。

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

各成功メッセージの出力箇所を網羅的に確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/@tailwindcss-upgrade/src/index.ts` | 行172, 256, 275, 330, 335, 356, 358の7箇所で `success()` が呼び出される流れを理解する |

**主要処理フロー**:
1. **行172**: JS設定ファイルマイグレーション完了メッセージ
2. **行256**: スタイルシート書き込み完了メッセージ（`isTailwindRoot` 条件付き）
3. **行275**: パッケージ更新完了メッセージ（パッケージごとにループ）
4. **行330**: テンプレートマイグレーション完了メッセージ（設定ファイル有り）
5. **行335**: テンプレートマイグレーション完了メッセージ（設定ファイル無し）
6. **行356**: 最終結果通知（変更あり）
7. **行358**: 最終結果通知（変更なし）

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

```
index.ts :: run()
    │
    ├─ [JS設定マイグレーション]
    │      └─ renderer.ts :: success("Migrated configuration file: ...")
    │
    ├─ [スタイルシート書き込み]
    │      └─ renderer.ts :: success("Migrated stylesheet: ...")
    │
    ├─ [パッケージ更新]
    │      └─ renderer.ts :: success("Updated package: ...") × N
    │
    ├─ [テンプレートマイグレーション]
    │      └─ renderer.ts :: success("Migrated templates for ...")
    │
    └─ [最終結果判定]
           ├─ git.ts :: isRepoDirty()
           └─ renderer.ts :: success("Verify..." or "No changes...")
```

### データフロー図

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

各処理ステップ ──────▶ 処理結果判定
                           │
                     成功の場合
                           │
                           ▼
ファイルパス情報 ──────▶ relative() → highlight()
                           │
                           ▼
                     success() ──────────▶ stderr（完了メッセージ）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/@tailwindcss-upgrade/src/index.ts` | ソース | upgradeコマンドのエントリーポイント。7箇所で成功メッセージを出力 |
| renderer.ts | `packages/@tailwindcss-upgrade/src/utils/renderer.ts` | ソース | `success()`, `highlight()`, `relative()`, `eprintln()` 等のCLI出力ユーティリティ |
| git.ts | `packages/@tailwindcss-upgrade/src/utils/git.ts` | ソース | `isRepoDirty()` 関数。最終結果判定で使用 |
| stylesheet.ts | `packages/@tailwindcss-upgrade/src/stylesheet.ts` | ソース | `Stylesheet` クラス。`file`, `isTailwindRoot` プロパティを提供 |
