# 通知設計書 16-小数バージョン警告

## 概要

本ドキュメントは、`@babel/helper-compilation-targets`において、ターゲット指定で小数バージョン（例: `6.10`）を使用した場合に出力される警告通知の仕様を定義する。

### 本通知の処理概要

この通知は、開発者がBabelのターゲット設定でブラウザ/環境のバージョンを小数（number型）で指定した場合に、予期しないバージョン解釈が発生する可能性について警告を出力する機能である。

**業務上の目的・背景**：JavaScriptでは、数値`6.10`は`6.1`として解釈される（末尾のゼロは削除される）。このため、ターゲット設定で`chrome: 6.10`と指定すると、意図に反して`chrome: 6.1`として扱われる。この警告は、開発者に文字列形式でのバージョン指定を推奨し、予期しないトランスパイル結果を防ぐために存在する。

**通知の送信タイミング**：`getTargets`関数内で、ターゲットの値がnumber型かつ小数を含む場合（`value % 1 !== 0`）に送信される。

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

**通知内容の概要**：小数バージョンを使用しているターゲットの一覧と、文字列形式でのバージョン指定を推奨する警告メッセージ。

**期待されるアクション**：開発者はターゲットバージョンを文字列形式（例: `"6.10"`）で指定するよう設定を見直すことが推奨される。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
Warning, the following targets are using a decimal version:

  {ターゲット名}: {バージョン値}
  ...

We recommend using a string for minor/patch versions to avoid numbers like 6.10
getting parsed as 6.1, which can lead to unexpected behavior.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| ターゲット名 | 小数バージョンが検出されたターゲット名 | `target` 変数 | Yes |
| バージョン値 | 検出された小数バージョン | `value` 変数 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | getTargets関数の実行（outputDecimalWarning関数内） | `decimalTargets.length > 0` | 小数バージョンを使用しているターゲットが1つ以上ある場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| decimalTargets.length === 0 | 小数バージョンを使用しているターゲットがない場合 |
| 全てのバージョンが文字列または整数 | 値がnumber型でないか、整数の場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[getTargets呼び出し] --> B[ターゲットをループ処理]
    B --> C{値がnumber型?}
    C -->|No| D[次のターゲットへ]
    C -->|Yes| E{value % 1 !== 0?<br>小数を含む?}
    E -->|No| D
    E -->|Yes| F[decimalWarningsに追加]
    F --> D
    D --> G{全ターゲット処理完了?}
    G -->|No| B
    G -->|Yes| H[outputDecimalWarning呼び出し]
    H --> I{decimalTargets.length > 0?}
    I -->|No| J[警告なし]
    I -->|Yes| K[console.warn出力]
    K --> L[結果を返す]
    J --> L
```

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

### 参照テーブル一覧

該当なし（ヘルパーライブラリのため、データベースアクセスは行わない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限なし | getTargets呼び出し時に一度だけ出力 |

### 配信時間帯

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

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

- ターゲット名とバージョン値を出力するが、これは通常機密情報ではない
- ローカル環境のコンソールへの出力のため、情報漏洩リスクは低い

## 備考

- JavaScriptの数値リテラル`6.10`は`6.1`と等価であり、これはJavaScriptの仕様による
- 文字列`"6.10"`を使用することで、意図したバージョンを正確に指定できる
- この警告はBabel使用時のよくある設定ミスを防ぐために追加された

---

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

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

### 推奨読解順序

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

まず、ターゲットの型定義と decimalWarnings 配列の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.d.ts | `packages/babel-helper-compilation-targets/src/types.d.ts` | Targets型とTarget型の定義 |
| 1-2 | index.ts | `packages/babel-helper-compilation-targets/src/index.ts` | decimalWarnings配列の構造（293行目） |

**読解のコツ**: `decimalWarnings`は`{ target: string; value: number }[]`の配列で、小数バージョンが検出されたターゲットを収集する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-helper-compilation-targets/src/index.ts` | getTargets関数の開始（204行目） |
| 2-2 | index.ts | `packages/babel-helper-compilation-targets/src/index.ts` | outputDecimalWarning関数（114-129行目） |

**主要処理フロー**:
1. **292-300行目**: ターゲットをループし、小数バージョンを検出
2. **313行目**: outputDecimalWarning関数の呼び出し

#### Step 3: 小数バージョン検出と警告出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-helper-compilation-targets/src/index.ts` | 小数バージョン検出（298行目） |
| 3-2 | index.ts | `packages/babel-helper-compilation-targets/src/index.ts` | outputDecimalWarning関数全体（114-129行目） |

**主要処理フロー**:
- **298行目**: `typeof value === "number" && value % 1 !== 0`の条件チェック
- **299行目**: decimalWarningsへの追加
- **117-119行目**: decimalTargets.length > 0のチェック
- **121-128行目**: console.warn出力（複数行メッセージ）

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

```
getTargets (index.ts:204)
    │
    ├─ ターゲットループ (294-311行目)
    │      └─ 小数バージョン検出 (298行目)
    │             └─ decimalWarnings.push (299行目)
    │
    └─ outputDecimalWarning (313行目)
           │
           └─ console.warn (121-128行目)
                  └─ 条件: decimalTargets.length > 0
```

### データフロー図

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

InputTargets {            getTargets
  chrome: 6.10,      ───▶ ├─ ターゲットループ
  firefox: 60             │      └─ 小数検出
}                         ├─ decimalWarnings構築
                          └─ outputDecimalWarning     ───▶ console.warn
                                                           (条件付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-helper-compilation-targets/src/index.ts` | ソース | getTargets関数とoutputDecimalWarning関数の実装 |
| types.d.ts | `packages/babel-helper-compilation-targets/src/types.d.ts` | ソース | Targets型、Target型、InputTargets型の定義 |
| targets.ts | `packages/babel-helper-compilation-targets/src/targets.ts` | ソース | TargetNames定数とbrowserNameMapの定義 |
| utils.ts | `packages/babel-helper-compilation-targets/src/utils.ts` | ソース | semverify等のユーティリティ関数 |
