# 通知設計書 19-ソースマップ警告

## 概要

本ドキュメントは、`@babel/core`において、インラインソースマップの解析に失敗した場合に出力される警告通知の仕様を定義する。

### 本通知の処理概要

この通知は、Babelがソースコード内に埋め込まれたインラインソースマップ（base64エンコードされたソースマップコメント）を解析しようとした際、何らかの理由で解析に失敗した場合に警告を出力する機能である。

**業務上の目的・背景**：ソースマップはトランスパイル後のコードを元のソースコードにマッピングするために使用される重要な機能である。Babelは入力ファイルに含まれるインラインソースマップを検出し、それを基に出力ソースマップを生成する。インラインソースマップが破損している、または不正な形式の場合、解析に失敗するが、Babelはこの場合に警告を出力してソースマップなしで処理を継続する。

**通知の送信タイミング**：`normalizeFile`関数内で、インラインソースマップのコメントが検出され、`convertSourceMap.fromComment`による解析が失敗した場合に送信される。

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

**通知内容の概要**：不明なインラインソースマップが破棄されたこと、対象ファイル名、および発生したエラーを含む警告メッセージ。

**期待されるアクション**：開発者は入力ファイルのソースマップコメントを確認し、正しいbase64エンコードされたJSON形式になっているか検証することが推奨される。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
discarding unknown inline input sourcemap {ファイル名} {エラーオブジェクト}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| ファイル名 | 処理中のファイル名 | `options.filename` | Yes |
| エラーオブジェクト | 解析失敗時のエラー | `catch`節の`err` | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | normalizeFile関数の実行 | インラインソースマップコメントが存在し、`convertSourceMap.fromComment`がエラーをスローした場合 | base64ソースマップの解析に失敗した場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| options.inputSourceMap === false | ソースマップ入力が無効化されている場合 |
| options.inputSourceMap がオブジェクト | 明示的なソースマップオブジェクトが渡されている場合 |
| インラインソースマップコメントがない | AST内にソースマップコメントが見つからない場合 |
| 解析が成功した場合 | convertSourceMap.fromCommentがエラーなく完了した場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[normalizeFile呼び出し] --> B{options.inputSourceMap<br>=== false?}
    B -->|Yes| C[ソースマップ処理をスキップ]
    B -->|No| D{options.inputSourceMap<br>がオブジェクト?}
    D -->|Yes| E[明示的ソースマップを使用]
    D -->|No| F[インラインソースマップを検索]
    F --> G{インラインコメントが<br>見つかった?}
    G -->|No| H[外部ソースマップを検索]
    G -->|Yes| I[convertSourceMap.fromComment<br>で解析]
    I --> J{解析成功?}
    J -->|Yes| K[inputMapに設定]
    J -->|No| L[console.warn出力]
    L --> H
    H --> M[処理続行]
    C --> M
    E --> M
    K --> M
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ソースマップ解析エラー | base64デコード失敗、JSON解析失敗など | 警告を出力し、ソースマップなしで処理を継続 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限なし | ファイル処理ごとに一度だけ出力 |

### 配信時間帯

制限なし（Babelコンパイル実行時）

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

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

## 備考

- インラインソースマップは `//# sourceMappingURL=data:application/json;base64,...` の形式で埋め込まれる
- `convert-source-map`パッケージを使用してソースマップを解析している
- 外部ソースマップ（ファイル参照）の解析失敗は、このwarningではなくdebugログに出力される
- インラインソースマップが破損している場合でも、コンパイル自体は正常に完了する

---

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

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

### 推奨読解順序

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

まず、ソースマップ関連の型定義と正規表現を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | normalize-file.ts | `packages/babel-core/src/transformation/normalize-file.ts` | INLINE_SOURCEMAP_REGEX（20-21行目） |
| 1-2 | normalize-file.ts | `packages/babel-core/src/transformation/normalize-file.ts` | NormalizedFile型（25-29行目） |

**読解のコツ**: `INLINE_SOURCEMAP_REGEX`はbase64エンコードされたインラインソースマップコメントにマッチする。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | normalize-file.ts | `packages/babel-core/src/transformation/normalize-file.ts` | normalizeFile関数（31行目） |

**主要処理フロー**:
1. **53-59行目**: options.inputSourceMapの処理
2. **61-73行目**: インラインソースマップの検出と解析
3. **67-72行目**: try-catch内での警告出力

#### Step 3: インラインソースマップ警告処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | normalize-file.ts | `packages/babel-core/src/transformation/normalize-file.ts` | インラインソースマップ処理（61-74行目） |

**主要処理フロー**:
- **62行目**: `extractComments(INLINE_SOURCEMAP_REGEX, ast)`でコメント検出
- **63-66行目**: try-catchブロック開始、`convertSourceMap.fromComment`呼び出し
- **66-72行目**: catch節でのconsole.warn出力

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

```
normalizeFile (normalize-file.ts:31)
    │
    ├─ options.inputSourceMap チェック (53-59行目)
    │      └─ convertSourceMap.fromObject (58行目)
    │
    ├─ extractComments (62行目)
    │      └─ INLINE_SOURCEMAP_REGEX でマッチ
    │
    └─ try-catch (64-72行目)
           ├─ convertSourceMap.fromComment (65行目)
           │      └─ 成功: inputMap設定
           └─ catch (66行目)
                  └─ console.warn (67-70行目)
```

### データフロー図

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

code: string              normalizeFile
ast: t.File          ───▶ ├─ extractComments
options: {                │      └─ インラインソースマップ検出
  inputSourceMap,         ├─ convertSourceMap.fromComment
  filename                │      └─ 解析試行
}                         └─ エラーハンドリング        ───▶ console.warn
                                                           (解析失敗時)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| normalize-file.ts | `packages/babel-core/src/transformation/normalize-file.ts` | ソース | ファイル正規化とソースマップ処理 |
| file/file.ts | `packages/babel-core/src/transformation/file/file.ts` | ソース | Fileクラスの定義 |
| validation/options.ts | `packages/babel-core/src/config/validation/options.ts` | ソース | ResolvedOptions型の定義 |
