# 通知設計書 24-CLIエラー出力

## 概要

本ドキュメントは、`@babel/cli`におけるコマンドラインオプションのバリデーションエラーを標準エラー出力に出力する機能の設計について記載する。

### 本通知の処理概要

この通知は、Babel CLIが起動された際に、コマンドラインオプションの組み合わせが不正である場合や、必須オプションが不足している場合に、エラーメッセージを標準エラー出力に出力する機能を提供する。

**業務上の目的・背景**：Babel CLIは複数のオプションを組み合わせて使用するが、一部のオプションは互いに排他的であったり、依存関係があったりする。例えば、`--out-file`と`--out-dir`は同時に指定できない。これらの不正な組み合わせを検出し、ユーザーに明確なエラーメッセージを提供することで、正しいCLIの使用方法を案内する。

**通知の送信タイミング**：`parseArgv`関数でコマンドライン引数を解析した直後、バリデーションチェックでエラーが検出された場合に、コンパイル処理開始前にエラーメッセージが出力される。

**通知の受信者**：Babel CLIを実行しているユーザー、CI/CDパイプラインのログを監視している開発者・運用者が対象。

**通知内容の概要**：エラーメッセージには「babel:」プレフィックスと、検出された各エラーの内容が含まれる。ファイルが存在しない、オプションの組み合わせが不正、必須オプションが不足しているなどのエラーが報告される。

**期待されるアクション**：ユーザーは、エラーメッセージの内容を確認し、コマンドラインオプションを修正してBabel CLIを再実行することが期待される。

## 通知種別

コンソールエラー（console.error）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高 |
| リトライ | 無 |

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

標準エラー出力（stderr）に対してconsole.errorで出力される。各エラーは個別の行として出力される。

## 通知テンプレート

### コンソール出力

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr（console.error経由） |
| 形式 | プレーンテキスト（複数行） |

### 本文テンプレート

```
babel:
  ${error1}
  ${error2}
  ...
```

### 具体的なエラーメッセージ例

| エラー種別 | メッセージ |
|----------|----------|
| ファイル不存在 | `{filename} does not exist` |
| 出力ディレクトリ必須 | `--out-dir requires filenames` |
| オプション競合 | `--out-file and --out-dir cannot be used together` |
| 相対パス指定必須 | `--relative requires --out-dir usage` |
| watchモード必須 | `--watch requires --out-file or --out-dir` |
| watchモードファイル必須 | `--watch requires filenames` |
| skip-initial-build必須 | `--skip-initial-build requires --watch` |
| delete-dir-on-start必須 | `--delete-dir-on-start requires --out-dir` |
| verbose/quiet競合 | `--verbose and --quiet cannot be used together` |
| stdin必須 | `stdin compilation requires either -f/--filename [filename] or --no-babelrc` |
| 拡張子オプション競合 | `--out-file-extension cannot be used with --keep-file-extension` |

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | 添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| error | 個別のエラーメッセージ | バリデーション処理 | Yes |
| filename | 存在しないファイル名 | コマンドライン引数 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLIオプション解析 | parseArgv関数の呼び出し | バリデーションエラーが1つ以上存在 | CLI起動時のオプション解析 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| エラーなし | すべてのバリデーションチェックが通過した場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[parseArgv関数呼び出し] --> B[program.parse実行]
    B --> C[ファイル存在チェック]
    C --> D{エラーあり?}
    D -->|Yes| E[エラー配列に追加]
    D -->|No| F[次のチェックへ]
    E --> F
    F --> G[オプション組み合わせチェック]
    G --> H{エラーあり?}
    H -->|Yes| I[エラー配列に追加]
    H -->|No| J[次のチェックへ]
    I --> J
    J --> K[全チェック完了]
    K --> L{errors.length > 0?}
    L -->|Yes| M[console.error "babel:"]
    M --> N[各エラーをconsole.errorで出力]
    N --> O[nullを返す]
    L -->|No| P[CmdOptionsを返す]
    O --> Q[終了]
    P --> Q
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | データベースは使用しない |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | データベースは使用しない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ファイル不存在 | 指定されたファイルが存在しない | 正しいファイルパスを指定 |
| オプション競合 | 互いに排他的なオプションが同時に指定された | 一方のオプションを削除 |
| 依存オプション不足 | あるオプションが別のオプションを必要とする | 依存オプションを追加 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（CLI実行時に同期的に出力）

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

- ファイルパスが出力されるが、これはユーザーが指定したものであり、通常は問題ない
- CI/CDログに記録される可能性があるが、機密情報は含まれない

## 備考

- エラーが検出された場合、parseArgv関数はnullを返し、コンパイル処理は開始されない
- 複数のエラーが同時に検出された場合、すべてのエラーが一度に出力される
- commander.jsライブラリを使用してオプション解析を行っている

---

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

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

### 推奨読解順序

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

まず、CmdOptions型の定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | options.ts | `packages/babel-cli/src/babel/options.ts` | CmdOptions型の定義（169-190行目） |

**読解のコツ**: `babelOptions`と`cliOptions`の2つのセクションに分かれていることを確認する。

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

警告を出力するparseArgv関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | options.ts | `packages/babel-cli/src/babel/options.ts` | parseArgv関数の実装（192-337行目） |

**主要処理フロー**:
1. **行194**: program.parseでコマンドライン引数を解析
2. **行198**: errors配列を初期化
3. **行200-217**: ファイル存在チェックとエラー収集
4. **行219-267**: 各種オプション組み合わせのバリデーション
5. **行269-275**: エラーがある場合のconsole.error出力

#### Step 3: オプション定義を理解する

CLIオプションがどのように定義されているかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | options.ts | `packages/babel-cli/src/babel/options.ts` | program.optionの定義（12-167行目） |

**主要処理フロー**:
- 各オプションがcommander.jsのprogram.optionで定義されている

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

```
babel CLI エントリーポイント
    │
    └─ parseArgv(args)
           │
           ├─ program.parse(args)
           │
           ├─ ファイル存在チェック
           │      └─ fs.existsSync(filename)
           │
           ├─ オプション組み合わせバリデーション
           │      ├─ --out-dir と filenames
           │      ├─ --out-file と --out-dir
           │      ├─ --relative と --out-dir
           │      ├─ --watch と --out-file/--out-dir
           │      └─ ... 他のチェック
           │
           └─ エラー出力
                  ├─ console.error("babel:")
                  └─ errors.forEach(e => console.error("  " + e))
```

### データフロー図

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

コマンドライン引数 ───▶ parseArgv関数 ───▶ CmdOptions または null
                              │
                              ▼
                        バリデーション
                              │
                              ▼ (エラーあり)
                        console.error ───▶ stderr（エラーメッセージ）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| options.ts | `packages/babel-cli/src/babel/options.ts` | ソース | CLIオプション解析とバリデーション |
| index.ts | `packages/babel-cli/src/babel/index.ts` | ソース | CLIのエントリーポイント |
| dir.ts | `packages/babel-cli/src/babel/dir.ts` | ソース | ディレクトリコンパイル処理 |
| file.ts | `packages/babel-cli/src/babel/file.ts` | ソース | ファイルコンパイル処理 |
