# 通知設計書 17-非推奨API警告

## 概要

本ドキュメントは、`@babel/types`において、非推奨のAPIを使用した場合に出力される警告通知の仕様を定義する。

### 本通知の処理概要

この通知は、開発者がBabelの`@babel/types`パッケージで非推奨となったAPIを使用した場合に、新しいAPIへの移行を促す警告を出力する機能である。

**業務上の目的・背景**：Babelは継続的に進化しており、一部のAPIは新しい実装に置き換えられている。非推奨APIの使用を継続すると、将来のメジャーバージョンで動作しなくなる可能性がある。この警告は、開発者に非推奨APIの使用を通知し、新しいAPIへの移行を促すために存在する。特に、外部パッケージ（プラグインなど）からの使用については、パッケージの更新により自動的に解決されるため、内部パッケージからの呼び出しでは警告を抑制する仕組みがある。

**通知の送信タイミング**：`deprecationWarning`関数が呼び出された時、かつ同じ警告が以前に出力されていない場合に送信される。さらに、呼び出し元が内部パッケージ（`@babel/*`）の場合は警告が抑制される。

**通知の受信者**：Babelを使用してAST操作を行う開発者（プラグイン作成者など）。コンソール出力を通じて通知される。

**通知内容の概要**：非推奨API名、新しいAPI名、および呼び出し元のスタックトレースを含む警告メッセージ。

**期待されるアクション**：開発者は新しいAPIに移行するか、使用しているプラグイン/パッケージを最新バージョンに更新することが推奨される。

## 通知種別

コンソール出力（console.warn）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 中 |
| リトライ | なし（コンソール出力のため） |

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

標準エラー出力（stderr）経由でコンソールに出力される。Babelを実行している開発者に対して直接表示される。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 出力先 | console.warn |
| 形式 | テキスト（複数行） |

### 本文テンプレート

```
{prefix}`{oldName}` has been deprecated, please migrate to `{newName}`
    at {スタックトレース行1}
    at {スタックトレース行2}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| prefix | 警告メッセージのプレフィックス（デフォルト: 空文字） | `prefix`パラメータ | No |
| oldName | 非推奨API名 | `oldName`パラメータ | Yes |
| newName | 新しいAPI名 | `newName`パラメータ | Yes |
| スタックトレース | 呼び出し元のスタックトレース（2行） | `captureShortStackTrace`関数 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | deprecationWarning関数の実行 | `!warnings.has(cacheKey)` かつ `!internal` | 同じ警告が未出力かつ外部パッケージからの呼び出しの場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| warnings.has(cacheKey) | 同じcacheKeyで既に警告が出力されている場合 |
| internal === true | 呼び出し元が内部パッケージ（@babel/*）の場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[deprecationWarning呼び出し] --> B{warnings.has<br>cacheKey?}
    B -->|Yes| C[早期リターン]
    B -->|No| D[warnings.add cacheKey]
    D --> E[captureShortStackTrace呼び出し]
    E --> F{internal === true?}
    F -->|Yes| C
    F -->|No| G[console.warn出力]
    G --> H[終了]
    C --> H
```

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

### 参照テーブル一覧

該当なし（ユーティリティ関数のため、データベースアクセスは行わない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | - | この警告自体はエラーではなく、処理を中断しない |

### リトライ仕様

該当なし（一度の警告出力のみ、同じcacheKeyでは重複出力されない）

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 重複抑制 | 同じcacheKeyでは一度だけ出力 |

### 配信時間帯

制限なし（API呼び出し時）

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

- API名とスタックトレースを出力するが、これは通常機密情報ではない
- スタックトレースにはファイルパスが含まれる可能性があるが、開発環境での使用を前提としている
- ローカル環境のコンソールへの出力のため、情報漏洩リスクは低い

## 備考

- `warnings` Setを使用して同じ警告の重複出力を防止している
- 内部パッケージからの呼び出しは自動的にスキップされる（パッケージ更新で解決されるため）
- `captureShortStackTrace`関数はV8のスタックトレースAPIを使用している
- スタックトレースは呼び出し元を特定するために2行のみ取得される

---

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

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

### 推奨読解順序

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

まず、`warnings` Setと関数のシグネチャを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | deprecationWarning.ts | `packages/babel-types/src/utils/deprecationWarning.ts` | warnings Set（1行目） |
| 1-2 | deprecationWarning.ts | `packages/babel-types/src/utils/deprecationWarning.ts` | deprecationWarning関数シグネチャ（3-8行目） |

**読解のコツ**: `warnings`はモジュールスコープのSetで、同じ警告の重複出力を防ぐために使用される。

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

処理の起点となる`deprecationWarning`関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | deprecationWarning.ts | `packages/babel-types/src/utils/deprecationWarning.ts` | deprecationWarning関数（3-23行目） |

**主要処理フロー**:
1. **9行目**: warnings.has(cacheKey)のチェック
2. **10行目**: warnings.add(cacheKey)で記録
3. **12行目**: captureShortStackTrace呼び出し
4. **13-18行目**: 内部パッケージチェックと早期リターン
5. **20-22行目**: console.warn出力

#### Step 3: スタックトレース取得処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | deprecationWarning.ts | `packages/babel-types/src/utils/deprecationWarning.ts` | captureShortStackTrace関数（25-46行目） |

**主要処理フロー**:
- **26行目**: Error.stackTraceLimitとError.prepareStackTraceの保存
- **29-32行目**: カスタムprepareStackTraceの設定
- **34行目**: new Error().stackでスタックトレース取得
- **40-44行目**: internalフラグの判定とtraceの構築

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

```
deprecationWarning (deprecationWarning.ts:3)
    │
    ├─ warnings.has (9行目)
    │
    ├─ warnings.add (10行目)
    │
    ├─ captureShortStackTrace (12行目)
    │      ├─ Error.prepareStackTrace設定 (30-32行目)
    │      ├─ new Error().stack (34行目)
    │      └─ internal判定・trace構築 (40-44行目)
    │
    └─ console.warn (20-22行目)
           └─ 条件: !internal
```

### データフロー図

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

deprecationWarning(       deprecationWarning
  oldName,           ───▶ ├─ 重複チェック
  newName,                 ├─ captureShortStackTrace
  prefix,                  │      └─ スタックトレース取得
  cacheKey                 ├─ 内部パッケージ判定
)                          └─ メッセージ構築          ───▶ console.warn
                                                           (条件付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| deprecationWarning.ts | `packages/babel-types/src/utils/deprecationWarning.ts` | ソース | 非推奨警告のメイン実装 |
