# 通知設計書 8-オプション引数の曖昧さ警告

## 概要

本ドキュメントは、babel-nodeコマンドにおいて、スクリプト名の後に渡されたオプションがBabelとNode.jsの両方で有効な場合に警告を出力する機能について設計内容を記載する。

### 本通知の処理概要

この通知は、`babel-node script.js --some-option` のように、スクリプト名の後にオプションを指定した際、そのオプションがBabelとNode.jsの両方で認識される可能性がある場合に警告を表示する機能である。

**業務上の目的・背景**：babel-nodeはNode.jsランタイム上でBabelによるトランスパイルを行いながらスクリプトを実行するツールである。Babel 7以前では、スクリプト名の後に指定されたオプションもBabelのオプションとして解釈されていたが、現在はスクリプト自体への引数として渡される。この動作変更により、開発者が意図したとおりにオプションが解釈されない可能性があるため、曖昧な場合に警告を出力して開発者に注意を促す。

**通知の送信タイミング**：babel-nodeコマンドの引数解析時、スクリプト名の後に渡されたオプションの中に、BabelまたはNode.js/V8で有効なオプションが含まれている場合に送信される。

**通知の受信者**：コマンドを実行した開発者（標準エラー出力を監視しているユーザー）

**通知内容の概要**：どのオプションが曖昧かを示し、Babelに渡したい場合とスクリプトに渡したい場合の両方のコマンド例を表示する。

**期待されるアクション**：開発者は、警告メッセージを確認し、意図した動作に合わせてコマンドライン引数の順序を調整するか、明示的なセパレータ（`--`）を使用してオプションの解釈を明確にする。

## 通知種別

コンソール出力（標準エラー出力：stderr）- console.warn使用

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（console.warn） |
| 優先度 | 中（警告） |
| リトライ | なし |

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

標準エラー出力（stderr）に固定。console.warnを使用。

## 通知テンプレート

### コンソール通知の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | 標準エラー出力（stderr） |
| フォーマット | プレーンテキスト |

### 本文テンプレート

```
Warning: {ambiguousArgsNames} {are} a valid option for Babel or Node.js, but {they} {are} defined after the script name. Up to Babel 7 {they} would have been passed to Babel, while now {they} {are} passed to the script itself.
  If the intention is to pass {them} to Babel, move {them} before the filename:
    babel-node {programArgs} {ambiguousArgs} {fileName} {unambiguousArgs}
  If passing {them} to the script is intended, you can silence this warning by explicitly using the -- separator before the script name:
    babel-node {programArgs} -- {fileName} {userArgs}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| ambiguousArgsNames | 曖昧なオプション名の一覧 | 検出されたオプション名の配列をjoin | Yes |
| are/they/them | 単数/複数形対応 | ambiguousArgsNames.lengthによる条件分岐 | Yes |
| programArgs | プログラム引数（スクリプト名より前） | splitArgs関数の戻り値 | Yes |
| ambiguousArgs | 曖昧な引数群 | 検出されたオプションとその値 | Yes |
| fileName | スクリプトファイル名 | splitArgs関数の戻り値 | Yes |
| unambiguousArgs | 曖昧でない引数群 | userArgsから曖昧なものを除外 | Yes |
| userArgs | ユーザー引数全体 | splitArgs関数の戻り値 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | babel-nodeコマンド実行 | 明示的セパレータ（`--`）未使用 かつ スクリプト後に曖昧なオプションがある | 引数解析時に発火 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 明示的セパレータ使用 | `babel-node -- script.js ...`のように`--`を使用した場合 |
| 曖昧なオプションなし | スクリプト後のオプションがBabel/Node.jsで認識されない場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[babel-node実行] --> B[引数分割: splitArgs]
    B --> C{明示的セパレータあり?}
    C -->|Yes| D[警告スキップ]
    C -->|No| E[V8フラグ取得: getV8Flags]
    E --> F[userArgs走査]
    F --> G{babelOptions または V8flag?}
    G -->|Yes| H[ambiguousArgsに追加]
    G -->|No| I[unambiguousArgsに追加]
    H --> J{全userArgs処理完了?}
    I --> J
    J -->|No| F
    J -->|Yes| K{ambiguousArgs.length > 0?}
    K -->|Yes| L[console.warn出力]
    K -->|No| M[警告スキップ]
    L --> N[子プロセス起動]
    M --> N
    D --> N
```

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

該当なし（データベースを使用しない）

## エラー処理

### エラーケース一覧

特にエラー処理は行われない。警告は情報提供のみで、処理は継続される。

### リトライ仕様

リトライなし

## 配信設定

### レート制限

該当なし

### 配信時間帯

制限なし

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

コマンドライン引数が出力されるため、引数に機密情報（APIキーなど）が含まれている場合は注意が必要。

## 備考

- 単数形/複数形の切り替えが行われる（it/they、is/are）
- v8flagsライブラリを使用してV8オプションを検出
- process.allowedNodeEnvironmentFlagsでNode.jsオプションも検出

---

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

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

### 推奨読解順序

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

この通知に関わるデータ構造は、引数の分類結果である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | babel-node.ts | `packages/babel-node/src/babel-node.ts` | splitArgsの戻り値構造（69-72行目）を確認 |
| 1-2 | split-args.ts | `packages/babel-node/src/split-args.ts` | splitArgs関数の詳細実装を確認 |

**読解のコツ**: splitArgsは`{ programArgs, fileName, userArgs, explicitSeparator }`を返す。

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

警告処理の流れを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | babel-node.ts | `packages/babel-node/src/babel-node.ts` | 即時実行関数内の処理（54-134行目） |

**主要処理フロー**:
1. **55-67行目**: babelOptionsとbabelOptionsWithValueの初期化
2. **69-72行目**: splitArgsで引数を分割
3. **86行目**: `if (!explicitSeparator)` で明示的セパレータの有無をチェック
4. **87行目**: `getV8Flags()` でV8フラグの判定関数を取得
5. **89-108行目**: userArgsを走査して曖昧なオプションを検出
6. **109-123行目**: 曖昧なオプションがある場合にconsole.warn出力

#### Step 3: 警告メッセージの詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | babel-node.ts | `packages/babel-node/src/babel-node.ts` | console.warn呼び出し（113-122行目） |

**主要処理フロー**:
- **110-112行目**: 単数/複数形の変数設定（them、they、are）
- **113-122行目**: 警告メッセージのテンプレートリテラル構築とconsole.warn出力

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

```
babel-node コマンド
    │
    └─ babel-node.ts (即時実行関数)
           │
           ├─ splitArgs(process.argv.slice(2), babelOptionsWithValue)
           │      └─ { programArgs, fileName, userArgs, explicitSeparator }
           │
           ├─ [!explicitSeparator] getV8Flags()
           │      └─ isV8flag関数を返す
           │
           ├─ userArgsを走査
           │      │
           │      └─ [babelOptions.has(arg) || isV8flag(arg)]
           │             └─ ambiguousArgsに追加
           │
           └─ [ambiguousArgsNames.length > 0]
                  │
                  └─ console.warn(...)
                         │
                         ├─ "Warning: {args} {are} a valid option..."
                         ├─ "  If the intention is to pass {them} to Babel..."
                         └─ "  If passing {them} to the script is intended..."
```

### データフロー図

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

process.argv ──────────────▶ splitArgs()
                                   │
                                   ├─ programArgs
                                   ├─ fileName
                                   ├─ userArgs
                                   └─ explicitSeparator
                                          │
                                          ▼
                                   [!explicitSeparator]
                                          │
                                          ▼
                                   getV8Flags()
                                          │
                                          ▼
                                   userArgs走査
                                          │
                                          ▼
                                   ambiguousArgs検出
                                          │
                                          ▼
                                   [ambiguousArgs.length > 0]
                                          │
                                          ▼
                                   console.warn() ───────▶ stderr: "Warning: ..."
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| babel-node.ts | `packages/babel-node/src/babel-node.ts` | ソース | メインエントリーポイントと警告処理 |
| split-args.ts | `packages/babel-node/src/split-args.ts` | ソース | コマンドライン引数の分割処理 |
| program-setup.ts | `packages/babel-node/src/program-setup.ts` | ソース | commander.jsのプログラム設定 |
| v8flags | 外部パッケージ | ライブラリ | V8オプションの列挙 |
