# 通知設計書 12-プラグイン重複警告

## 概要

本ドキュメントは、Babelパーサー（`@babel/parser`）において、パーサープラグインの設定オプション重複時に出力される警告通知の仕様を定義する。

### 本通知の処理概要

この通知は、非推奨のパーサープラグインが使用された場合や、import attributes関連の非推奨構文が使用された場合に、開発者に警告を出力する機能である。

**業務上の目的・背景**：Babelパーサーは継続的に進化しており、一部のプラグインや構文は非推奨となり、新しい代替機能に置き換えられる。`deprecatedImportAssert`プラグインやimport attributesの`deprecatedAssertSyntax`オプションは、ES Modules仕様の変更に伴い非推奨となった。この警告は、開発者に新しい構文への移行を促し、将来のBabelバージョンでの互換性を確保するために存在する。

**通知の送信タイミング**：パーサーのプラグイン検証時（`validatePlugins`関数が呼び出された時）に、`deprecatedImportAssert`プラグインが使用されているか、または`importAttributes`プラグインで`deprecatedAssertSyntax`オプションがtrueに設定されている場合に送信される。

**通知の受信者**：Babelを使用してJavaScript/TypeScriptコードをパースする開発者。コンソール出力を通じて通知される。

**通知内容の概要**：非推奨プラグイン/オプションの削除通知と、代替となる新しい構文（import attributesの`with`キーワード）への移行案内。

**期待されるアクション**：開発者は`assert`スタイルのimport属性を`with`スタイルに移行し、非推奨のプラグインやオプションを設定から削除することが推奨される。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 出力先 | console.warn |
| 形式 | テキスト |

### 本文テンプレート

#### deprecatedImportAssertプラグイン使用時

```
`deprecatedImportAssert` has been removed in Babel 8, please use import attributes instead.
```

#### importAttributesプラグインのdeprecatedAssertSyntaxオプション使用時

```
The 'importAttributes' plugin has been removed in Babel 8. Please migrate any usage of `assert`-style attributes to `with`.
```

### 添付ファイル

該当なし

## テンプレート変数

該当なし（固定メッセージ）

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | validatePlugins関数の実行 | `pluginsMap.has("deprecatedImportAssert")` | deprecatedImportAssertプラグインが設定されている場合 |
| API呼び出し | validatePlugins関数の実行 | `pluginsMap.has("importAttributes") && pluginsMap.get("importAttributes").deprecatedAssertSyntax` | importAttributesプラグインでdeprecatedAssertSyntaxがtrueの場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| deprecatedImportAssertプラグインが未設定 | 当該プラグインが設定に含まれていない場合 |
| importAttributesプラグインが未設定またはdeprecatedAssertSyntaxがfalsy | オプションが設定されていないか、falsy値の場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[validatePlugins呼び出し] --> B{deprecatedImportAssert<br>プラグインが存在?}
    B -->|Yes| C[console.warn出力:<br>deprecatedImportAssert警告]
    B -->|No| D{importAttributesプラグインが存在?}
    C --> D
    D -->|Yes| E{deprecatedAssertSyntax<br>オプションがtrue?}
    D -->|No| F[警告なし]
    E -->|Yes| G[console.warn出力:<br>importAttributes警告]
    E -->|No| F
    G --> H[プラグイン検証続行]
    F --> H
```

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

### 参照テーブル一覧

該当なし（パーサー処理のため、データベースアクセスは行わない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし（一度の警告出力のみ）

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限なし | パーサー実行時に一度だけ出力 |

### 配信時間帯

制限なし（Babelパーサー実行時）

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

- プラグイン設定情報のみを出力し、ソースコードや機密情報は含まない
- ローカル環境のコンソールへの出力のため、情報漏洩リスクは低い

## 備考

- `moduleAttributes`プラグインと`importAssertions`プラグインはBabel 8で完全に削除され、エラーを投げる
- `deprecatedImportAssert`と`importAttributes.deprecatedAssertSyntax`は警告のみで、処理は継続される
- ES Modules仕様では`import ... assert {}`構文から`import ... with {}`構文への移行が進んでいる

---

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

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

### 推奨読解順序

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

まず、プラグインマップの構造と型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | plugin-utils.ts | `packages/babel-parser/src/plugin-utils.ts` | Plugin型とMixinPlugin型の定義（4-8行目） |

**読解のコツ**: プラグインは文字列（名前）とオプションオブジェクトのMapとして管理される。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | plugin-utils.ts | `packages/babel-parser/src/plugin-utils.ts` | validatePlugins関数の開始（13行目） |

**主要処理フロー**:
1. **14-20行目**: decoratorsとdecorators-legacyの競合チェック
2. **22-24行目**: flowとtypescriptの競合チェック
3. **65-75行目**: moduleAttributesとimportAssertionsの削除エラー
4. **77-88行目**: deprecatedImportAssertとimportAttributes警告処理

#### Step 3: 警告出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | plugin-utils.ts | `packages/babel-parser/src/plugin-utils.ts` | deprecatedImportAssert警告（77-80行目） |
| 3-2 | plugin-utils.ts | `packages/babel-parser/src/plugin-utils.ts` | importAttributes警告（81-88行目） |

**主要処理フロー**:
- **77-80行目**: `deprecatedImportAssert`プラグインの存在チェックと警告出力
- **81-88行目**: `importAttributes`プラグインの`deprecatedAssertSyntax`オプションチェックと警告出力

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

```
validatePlugins (plugin-utils.ts:13)
    │
    ├─ pluginsMap.has("deprecatedImportAssert")
    │      └─ console.warn (78-80行目)
    │
    └─ pluginsMap.has("importAttributes")
           └─ pluginsMap.get("importAttributes").deprecatedAssertSyntax
                  └─ console.warn (85-87行目)
```

### データフロー図

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

pluginsMap: Map<         validatePlugins
  string,            ───▶ ├─ プラグイン存在チェック  ───▶ console.warn
  any                     ├─ オプション値チェック         (条件付き)
>                         └─ メッセージ出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| plugin-utils.ts | `packages/babel-parser/src/plugin-utils.ts` | ソース | プラグイン検証ロジックのメイン実装 |
| typings.ts | `packages/babel-parser/src/typings.ts` | ソース | PluginConfig型の定義 |
| parser/index.ts | `packages/babel-parser/src/parser/index.ts` | ソース | Parserクラス（validatePluginsの呼び出し元） |
