# 通知設計書 6-アップグレード処理エラー

## 概要

本ドキュメントは、Tailwind CSS upgradeコマンド（`@tailwindcss/upgrade`）の各処理ステップでエラーが発生した際に、コンテキスト付きエラーメッセージを標準エラー出力に出力する通知仕様を定義する。

### 本通知の処理概要

upgradeコマンドの各マイグレーション処理ステップ（スタイルシート読み込み、分析、リンク、スタイルシート移行、分割）でエラーが発生した際に、例外メッセージをコンテキスト付きで赤色装飾して出力する通知処理である。プロセスは終了せず、処理を可能な限り継続する。

**業務上の目的・背景**：upgradeコマンドは多数のファイルを処理するため、一部のファイルでエラーが発生しても全体の処理を中断せずに可能な限り続行する設計となっている。エラーが発生したファイルやステップの情報を明確に通知することで、ユーザーがマイグレーション後に手動で対処すべき箇所を特定できるようにする。

**通知の送信タイミング**：以下の処理ステップでエラーが発生した際に送信される。
1. スタイルシート読み込み失敗時（行114）：`Stylesheet.load()` のPromise rejection
2. スタイルシート分析失敗時（行127）：`analyzeStylesheets()` のエラー
3. 設定リンク失敗時（行139）：`linkConfigsToStylesheets()` のエラー
4. スタイルシート移行失敗時（行207）：`migrateStylesheet()` のエラー（ファイル名付き）
5. スタイルシート分割失敗時（行217）：`splitStylesheets()` のエラー

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

**通知内容の概要**：各例外のエラーメッセージが赤色装飾付きで出力される。スタイルシート移行エラーの場合は対象ファイル名も付加される。

**期待されるアクション**：開発者はエラーメッセージを確認し、アップグレード完了後に該当ファイルを手動で修正する。必要に応じて、問題のあるファイルを除外してから再度upgradeコマンドを実行する。

## 通知種別

CLI標準エラー出力（stderr）

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

### メール通知の場合

該当なし（CLI出力のみ）

### 本文テンプレート

**スタイルシート読み込みエラー（行114）**:
```
│ ↳ {errorMessage}
```

**スタイルシート分析エラー（行127）**:
```
│ ↳ {errorMessage}
```

**設定リンクエラー（行139）**:
```
│ ↳ {errorMessage}
```

**スタイルシート移行エラー（行207）**:
```
│ ↳ {errorMessage} in `{filePath}`
```

**スタイルシート分割エラー（行217）**:
```
│ ↳ {errorMessage}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| errorMessage | エラーの例外メッセージ | `e?.message ?? e` から取得（Promiseの場合は `result.reason?.message ?? result.reason`） | Yes |
| filePath | エラーが発生したCSSファイルの相対パス | `relative(sheet.file!, base)` | Yes（スタイルシート移行エラーのみ） |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 内部処理 | Stylesheet.load() rejection | `result.status === 'rejected'` | CSSファイル読み込み失敗時 |
| 内部処理 | analyzeStylesheets() 例外 | try-catch でエラーキャッチ | スタイルシート分析失敗時 |
| 内部処理 | linkConfigsToStylesheets() 例外 | try-catch でエラーキャッチ（v3の場合のみ） | 設定ファイルリンク失敗時 |
| 内部処理 | migrateStylesheet() 例外 | try-catch でエラーキャッチ | 個別スタイルシート移行失敗時 |
| 内部処理 | splitStylesheets() 例外 | try-catch でエラーキャッチ（v3の場合のみ） | スタイルシート分割失敗時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 処理が正常に完了した場合 | エラーが発生しなかった場合、エラーメッセージは出力されない |
| v3以外で設定リンク/分割のエラー | `version.isMajor(3)` が `false` の場合、設定リンクと分割処理自体がスキップされる |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[アップグレード処理開始] --> B[Stylesheet.load 実行]
    B --> C{Promise結果}
    C -->|rejected| D[error: エラーメッセージ出力]
    C -->|fulfilled| E[次の処理へ]
    D --> E
    E --> F[analyzeStylesheets 実行]
    F --> G{例外発生?}
    G -->|Yes| H[error: エラーメッセージ出力]
    G -->|No| I[次の処理へ]
    H --> I
    I --> J[migrateStylesheet 実行]
    J --> K{例外発生?}
    K -->|Yes| L[error: ファイル名付きエラー出力]
    K -->|No| M[次の処理へ]
    L --> M
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| CSSパースエラー | CSSファイルの構文エラー | エラーメッセージを出力し、該当ファイルをスキップして処理を継続 |
| ファイルアクセスエラー | ファイルの読み取り権限がない等 | エラーメッセージを出力し、処理を継続 |
| マイグレーションロジックエラー | 未知のCSS構造やサポート外の記法 | エラーメッセージにファイル名を付加して出力し、処理を継続 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

エラーメッセージに例外のメッセージ文字列がそのまま含まれる。ファイルパス情報が出力される場合があるが、ユーザーのプロジェクト内の相対パスに変換される。内部的なスタックトレースは出力されない。

## 備考

- スタイルシート読み込みエラーのみ `Promise.allSettled` で処理されるため、個別の `result.reason` からエラーメッセージを取得する
- その他のエラーはすべて try-catch で処理され、`e?.message ?? e` でエラーメッセージを取得する
- スタイルシート移行エラーのみファイル名が付加される（`in ${highlight(relative(sheet.file!, base))}`）
- エラー発生後もプロセスは終了せず、可能な限り処理を継続する設計
- 全てのエラーメッセージに `{ prefix: '↳ ' }` が設定されている

---

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

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

### 推奨読解順序

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

エラー処理パターンとレンダリングの仕組みを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | renderer.ts | `packages/@tailwindcss-upgrade/src/utils/renderer.ts` | `error()` 関数が `log()` を赤色パイプ（`pc.red('│')`）で呼び出す仕組みを理解する |

**読解のコツ**: `error()` 関数は行116-118で定義されている。`success()` と同じ `log()` 関数を使用するが、`art` パラメータの色が `pc.red` に変わる。

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

各エラー出力箇所を網羅的に確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/@tailwindcss-upgrade/src/index.ts` | 行114, 127, 139, 207, 217の5箇所で `error()` が呼び出される。各箇所のtry-catchパターンとエラーメッセージの構築方法を理解する |

**主要処理フロー**:
1. **行112-116**: `Promise.allSettled` の結果をループし、`status === 'rejected'` のものからエラーメッセージを取得
2. **行124-128**: `analyzeStylesheets()` のtry-catch。エラーメッセージのみ出力
3. **行133-141**: `linkConfigsToStylesheets()` のtry-catch。`isMajor(3)` 条件付き
4. **行206-208**: `migrateStylesheet()` のtry-catch。ファイル名を `in ${highlight(relative())}` で付加
5. **行214-218**: `splitStylesheets()` のtry-catch。`isMajor(3)` 条件付き

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

```
index.ts :: run()
    │
    ├─ Promise.allSettled(Stylesheet.load(...))
    │      └─ rejected → renderer.ts :: error(result.reason.message)
    │
    ├─ try { analyzeStylesheets() } catch
    │      └─ catch → renderer.ts :: error(e.message)
    │
    ├─ try { linkConfigsToStylesheets() } catch  [v3のみ]
    │      └─ catch → renderer.ts :: error(e.message)
    │
    ├─ try { migrateStylesheet() } catch
    │      └─ catch → renderer.ts :: error(e.message + " in " + filePath)
    │
    └─ try { splitStylesheets() } catch  [v3のみ]
           └─ catch → renderer.ts :: error(e.message)
```

### データフロー図

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

各処理ステップ ──────▶ 例外キャッチ
                           │
                     エラーの場合
                           │
                           ▼
例外オブジェクト ──────▶ e?.message ?? e
                           │
(sheet.file) ──────▶ relative() → highlight()  [行207のみ]
                           │
                           ▼
                     error() ──────────────▶ stderr（エラーメッセージ）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/@tailwindcss-upgrade/src/index.ts` | ソース | upgradeコマンドのエントリーポイント。5箇所でエラーメッセージを出力 |
| renderer.ts | `packages/@tailwindcss-upgrade/src/utils/renderer.ts` | ソース | `error()`, `highlight()`, `relative()`, `eprintln()` 等のCLI出力ユーティリティ |
| stylesheet.ts | `packages/@tailwindcss-upgrade/src/stylesheet.ts` | ソース | `Stylesheet` クラス。`load()` メソッドでCSSファイルを読み込み |
| version.ts | `packages/@tailwindcss-upgrade/src/utils/version.ts` | ソース | `isMajor()` 関数。v3条件付きの処理で使用 |
