# 通知設計書 1-Gitディレクトリ未コミットエラー

## 概要

本ドキュメントは、Tailwind CSS upgradeコマンド（`@tailwindcss/upgrade`）実行時に、Git作業ディレクトリに未コミットの変更がある場合に出力されるエラーメッセージの通知仕様を定義する。

### 本通知の処理概要

upgradeコマンド実行時にGit作業ディレクトリの状態を検査し、未コミットの変更が検出された場合にエラーメッセージを標準エラー出力に出力してプロセスを終了する通知処理である。

**業務上の目的・背景**：Tailwind CSSのバージョンアップグレードは、CSSファイル・設定ファイル・テンプレートファイルなど多数のファイルを自動的に書き換える破壊的な操作である。未コミットの変更がある状態でアップグレードを実行すると、ユーザー自身の変更とアップグレードによる変更が混在し、問題発生時にロールバックが困難になる。このエラー通知により、ユーザーに事前にコミットまたはスタッシュを促し、安全なアップグレードを保証する。

**通知の送信タイミング**：`npx @tailwindcss/upgrade` コマンド実行直後、アップグレード処理本体が開始される前の初期バリデーション段階で送信される。具体的には `run()` 関数内の `isRepoDirty()` チェック時（`--force` フラグが指定されていない場合）に発生する。

**通知の受信者**：CLIを実行した開発者。標準エラー出力（stderr）に出力されるため、ターミナル上で直接確認する。

**通知内容の概要**：「Git directory is not clean. Please stash or commit your changes before migrating.」というエラーメッセージと、`--force` フラグで警告を抑制できる旨の情報メッセージが出力される。

**期待されるアクション**：開発者は未コミットの変更を `git stash` または `git commit` で保存した後、再度upgradeコマンドを実行する。あるいは、`--force` フラグを付与して強制的にアップグレードを実行する。

## 通知種別

CLI標準エラー出力（stderr）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（プロセス内直接出力） |
| 優先度 | 高（プロセス終了を伴う） |
| リトライ | 無し（即時出力） |

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

CLIを実行したプロセスの標準エラー出力（`process.stderr`）に対して `eprintln()` 関数経由で出力する。送信先の動的決定は行わない。

## 通知テンプレート

### メール通知の場合

該当なし（CLI出力のみ）

### 本文テンプレート

```
│ Git directory is not clean. Please stash or commit your changes before migrating.

│ You may use the `--force` flag to silence this warning and perform the migration.
```

※ 先頭の `│` は `renderer.ts` の `error()` / `info()` 関数による装飾（赤色/青色のパイプ文字）

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | 本通知は固定文字列で構成される | - | - |

※ `--force` フラグのハイライト表示は `highlight()` 関数で装飾される。

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI操作 | `npx @tailwindcss/upgrade` 実行 | `--force` フラグ未指定 かつ `isRepoDirty()` が `true` を返す | Git作業ディレクトリに未コミット変更がある場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `--force` フラグ指定時 | ユーザーが `--force` または `-f` フラグを指定した場合、Gitの状態チェック自体がスキップされる |
| Gitリポジトリ外の場合 | `isRepoDirty()` が `git status` コマンド失敗時に `false` を返すため、Git管理外ディレクトリではエラーは発生しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[upgradeコマンド実行] --> B{--force フラグ?}
    B -->|あり| C[Gitチェックスキップ]
    B -->|なし| D[isRepoDirty 実行]
    D --> E{Git作業ディレクトリは<br>クリーンか?}
    E -->|クリーン| C
    E -->|ダーティ| F[error メッセージ出力]
    F --> G[info メッセージ出力<br>--force フラグの案内]
    G --> H[process.exit 1]
    C --> I[アップグレード処理続行]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| Git未インストール | `git status` コマンドが実行不可 | `isRepoDirty()` が例外をキャッチし、`not a git repository` 以外のエラーの場合は `true` を返してエラー通知を発生させる |
| Gitリポジトリ外実行 | `.git` ディレクトリが存在しない | `isRepoDirty()` が `false` を返し、エラー通知は発生しない |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

本通知は固定文字列のみを出力するため、個人情報や機密情報の漏洩リスクはない。Git作業ディレクトリの内容（ファイル名や変更内容）は出力に含まれない。

## 備考

- `isRepoDirty()` は内部で `git status --porcelain` を実行し、その出力が空でない場合に `true` を返す
- このチェックはアップグレード処理の最初期に実行され、後続のバージョンチェックよりも先に行われる
- エラーメッセージは `renderer.ts` の `error()` 関数で赤色装飾され、情報メッセージは `info()` 関数で青色装飾される

---

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

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

### 推奨読解順序

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

通知メッセージの出力に使用されるレンダリングユーティリティの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | renderer.ts | `packages/@tailwindcss-upgrade/src/utils/renderer.ts` | `error()`, `info()`, `highlight()`, `eprintln()` 各関数の役割と出力形式を理解する |

**読解のコツ**: `error()` / `info()` / `success()` / `warn()` はすべて内部で `log()` 関数を呼び出し、`art` パラメータの色が異なるだけである。`eprintln()` は `process.stderr.write()` のラッパーである。

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

upgradeコマンドのメインエントリーポイントと、Gitチェックの呼び出し箇所を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/@tailwindcss-upgrade/src/index.ts` | `run()` 関数内の行51-59でGitディレクトリチェックが行われる流れを理解する |

**主要処理フロー**:
1. **行51**: `if (!flags['--force'])` で `--force` フラグの有無を確認
2. **行53**: `isRepoDirty()` を呼び出してGit作業ディレクトリの状態を検査
3. **行54**: `error()` 関数でエラーメッセージを出力
4. **行55-57**: `info()` 関数で `--force` フラグの案内メッセージを出力
5. **行58**: `process.exit(1)` でプロセスを終了

#### Step 3: Gitチェックロジックを理解する

Git作業ディレクトリの状態を判定する関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | git.ts | `packages/@tailwindcss-upgrade/src/utils/git.ts` | `isRepoDirty()` 関数が `git status --porcelain` コマンドで状態を判定するロジックを理解する |

**主要処理フロー**:
- **行5**: `execSync('git status --porcelain')` でGitステータスを取得
- **行6**: 出力が空でなければ `true`（ダーティ）を返す
- **行11**: `not a git repository` エラーの場合は `false` を返す（Git管理外ではチェックをスキップ）
- **行15**: その他のエラーの場合は `true` を返す（安全側に倒す）

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

```
index.ts :: run()
    │
    ├─ args() ... CLIオプション解析（--force フラグの取得）
    │
    ├─ git.ts :: isRepoDirty()
    │      └─ execSync('git status --porcelain')
    │
    ├─ renderer.ts :: error()
    │      └─ log() → eprintln() → process.stderr.write()
    │
    └─ renderer.ts :: info()
           └─ log() → eprintln() → process.stderr.write()
```

### データフロー図

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

CLIオプション ──────▶ flags['--force'] チェック
                           │
                           ▼
                     isRepoDirty() ──────▶ git status --porcelain
                           │
                           ▼
                     状態判定 ──────────────▶ error() → stderr
                                            info()  → stderr
                                            process.exit(1)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/@tailwindcss-upgrade/src/index.ts` | ソース | upgradeコマンドのエントリーポイント。行51-59でGitチェックを実行 |
| git.ts | `packages/@tailwindcss-upgrade/src/utils/git.ts` | ソース | `isRepoDirty()` 関数の実装。`git status --porcelain` でGit状態を判定 |
| renderer.ts | `packages/@tailwindcss-upgrade/src/utils/renderer.ts` | ソース | `error()`, `info()`, `highlight()`, `eprintln()` 等のCLI出力ユーティリティ |
| args.ts | `packages/@tailwindcss-upgrade/src/utils/args.ts` | ソース | CLIオプション解析。`--force` フラグの定義と解析 |
