# 通知設計書 3-SFCコンパイラ警告

## 概要

本ドキュメントは、Vue.jsのSingle File Component（.vue）コンパイラにおける警告通知機構の設計仕様を記述する。`packages/compiler-sfc/src/warn.ts`に実装されており、ANSIカラーコード付きの`console.warn`で開発者に通知する。`warnOnce`による重複出力抑制機能を持つ。

### 本通知の処理概要

この通知は、SFCコンパイル時に問題を検出した場合に、ANSIカラー付きの`console.warn`で開発者に通知する機構である。同一メッセージの重複出力を`warnOnce`関数で抑制する機能を備える。

**業務上の目的・背景**：SFCコンパイラは`.vue`ファイルをJavaScriptに変換するプロセスで動作する。このプロセス中に検出された問題（非推奨機能の使用、潜在的な問題パターンなど）を開発者に通知するために存在する。ビルドプロセス中の通知であるため、ターミナル上での視認性を高めるためにANSIエスケープコードによる黄色文字が使用される。

**通知の送信タイミング**：`.vue`ファイルのコンパイル時（ビルドプロセスまたはHMR時）に問題が検出された場合に発火する。`warnOnce`を使用した場合は同一メッセージにつき1回のみ出力される。

**通知の受信者**：アプリケーション開発者。ビルドツール（Vite、webpack等）のターミナル出力を通じて確認する。

**通知内容の概要**：`[@vue/compiler-sfc]`プレフィックス付きの黄色文字での警告メッセージが出力される。

**期待されるアクション**：開発者がSFCの記述を見直し、問題となるパターンを修正する。

## 通知種別

コンソール警告（`console.warn`、ANSIカラー付き）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 中 |
| リトライ | なし |

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

`console.warn`のみに出力する。ANSIエスケープコードによる黄色文字で表示される。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | N/A（コンソール出力） |
| 送信元名称 | `[@vue/compiler-sfc]` |
| 件名 | N/A |
| 形式 | テキスト（ANSIカラー付き） |

### 本文テンプレート

```
\x1b[1m\x1b[33m[@vue/compiler-sfc]\x1b[0m\x1b[33m {警告メッセージ}\x1b[0m
```

ANSIエスケープコードの意味：
- `\x1b[1m` - 太字
- `\x1b[33m` - 黄色文字
- `\x1b[0m` - リセット

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | N/A | N/A | コンソール出力のため添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| msg | 警告メッセージ本文 | 呼び出し元から渡される文字列引数 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ビルドプロセス | SFCコンパイル時の問題検出 | 常時（warn関数） | 毎回出力される |
| ビルドプロセス | SFCコンパイル時の問題検出 | 未出力メッセージ（warnOnce関数） | 同一メッセージは1回のみ |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `hasWarned[msg]` がtrue | warnOnce使用時、同一メッセージが既に出力済みの場合は抑止 |
| `process.env.NODE_ENV === 'production'` | warnOnce使用時、本番環境では抑止 |
| `__TEST__` がtrue | warnOnce使用時、テスト環境では抑止 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[SFCコンパイル中に問題検出] --> B{warnOnce or warn?}
    B -->|warnOnce| C{本番環境か?}
    C -->|Yes| Z[抑止: 何もしない]
    C -->|No| D{テスト中か?}
    D -->|Yes| Z
    D -->|No| E{同一メッセージ出力済みか?}
    E -->|Yes| Z
    E -->|No| F[hasWarned記録]
    F --> G[warn関数呼び出し]
    B -->|warn| G
    G --> H["console.warn(ANSIカラー付きメッセージ)"]
    H --> I[終了]
    Z --> I
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | N/A | データベースは使用しない |

### テーブル別参照項目詳細

本通知はデータベースを使用しない。以下のインメモリデータ構造を参照する。

| 参照データ | 用途 | 取得方法 |
|-----------|------|---------|
| hasWarned (Record<string, boolean>) | 重複出力抑制用の記録 | モジュールスコープのオブジェクト |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| N/A | N/A | データベースの更新は行わない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | N/A | 単純なconsole.warn呼び出しのためエラー処理は不要 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし（ただしwarnOnceは同一メッセージ1回のみ） |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし。ビルドプロセス実行時に動作する。

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

- コンパイル時の警告であるため、ランタイムには影響しない
- ファイルパス情報が含まれる可能性があるが、開発環境でのみ使用されるため問題ない

## 備考

- `[@vue/compiler-sfc]`プレフィックスはパッケージ名を示す
- ANSIエスケープコードはターミナル出力用であり、ブラウザコンソールでは正しく表示されない可能性がある
- `warnOnce`は`hasWarned`オブジェクトをモジュールスコープで保持するため、プロセスが終了するまで記録が保持される
- `warn`関数は末尾に改行（`\n`）を付加する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | warn.ts | `packages/compiler-sfc/src/warn.ts` | L1: hasWarnedオブジェクト（重複抑制用の記録マップ） |

**読解のコツ**: `Record<string, boolean>`型でメッセージ文字列をキーとして出力済みかどうかを記録する単純な構造。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | warn.ts | `packages/compiler-sfc/src/warn.ts` | L3-9: warnOnce関数。環境チェック、重複チェック、warn呼び出し |
| 2-2 | warn.ts | `packages/compiler-sfc/src/warn.ts` | L12-16: warn関数。ANSIカラー付きconsole.warn出力 |

**主要処理フロー**:
1. **L4-5**: `process.env.NODE_ENV === 'production'`チェック（Node.js環境判定）
2. **L6**: `!isNodeProd && !__TEST__ && !hasWarned[msg]`の3条件チェック
3. **L7**: `hasWarned[msg] = true`で出力済み記録
4. **L8**: `warn(msg)`を呼び出し
5. **L13-15**: ANSIエスケープコード付きでconsole.warnに出力

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

```
[SFCコンパイル処理]
    |
    +-- warnOnce(msg)                  [warn.ts:3]
    |       |
    |       +-- 環境チェック (production/test)
    |       +-- 重複チェック (hasWarned)
    |       +-- warn(msg)              [warn.ts:12]
    |               |
    |               +-- console.warn() [ANSIカラー付き]
    |
    +-- warn(msg)                      [warn.ts:12]（直接呼び出しも可能）
            |
            +-- console.warn()         [ANSIカラー付き]
```

### データフロー図

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

msg (string)          +-- warnOnce()                    +-- console.warn()
  |                   |     |                           |     黄色文字で
  +----------------->|     +-- 環境チェック              |     "[@vue/compiler-sfc] ..."
                      |     +-- hasWarned確認       ---->|
                      |     +-- warn()                  |
                      |           |                     |
                      |           +-- ANSIカラー付加    +-- 末尾改行付き
                      +--
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| warn.ts | `packages/compiler-sfc/src/warn.ts` | ソース | warn/warnOnce関数本体 |
