# 機能設計書 5-@babel/cli

## 概要

本ドキュメントは、Babelのコマンドラインインターフェースである`@babel/cli`パッケージの設計仕様を記述する。このパッケージは、コマンドラインから直接Babelトランスパイルを実行するツールを提供し、ファイル・ディレクトリのバッチ変換やウォッチモードをサポートする。

### 本機能の処理概要

**業務上の目的・背景**：開発者がビルドスクリプトやCIパイプラインでBabelを使用する際、コマンドラインからの直接実行が必要となる。@babel/cliは、シンプルなコマンドでファイルやディレクトリを変換し、ソースマップの生成、ウォッチモードによる自動再コンパイル等をサポートする。

**機能の利用シーン**：package.jsonのscriptsでビルドコマンドを定義する場合、CI/CDパイプラインでトランスパイルを実行する場合、開発中にウォッチモードで自動変換する場合に利用される。

**主要な処理内容**：
1. コマンドライン引数の解析
2. 単一ファイルまたはディレクトリの変換
3. 複数ファイルの単一出力への結合
4. ソースマップの生成と出力
5. ウォッチモードによるファイル監視と自動再コンパイル
6. 非コンパイルファイルのコピー

**関連システム・外部連携**：@babel/core（変換処理）、chokidar（ファイル監視）、commander（CLI引数解析）、glob（パターンマッチング）と連携する。

**権限による制御**：ファイルシステムの読み書き権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI（コマンドラインインターフェース）として動作 |

## 機能種別

コマンドラインツール

## 入力仕様

### 入力パラメータ（コマンドラインオプション）

| パラメータ名 | 型 | 必須 | 説明 | デフォルト |
|-------------|-----|-----|------|---------|
| [files...] | string[] | No | 変換対象のファイル/ディレクトリ | stdin |
| -f, --filename | string | No | stdin使用時のファイル名 | - |
| --presets | string[] | No | 使用するプリセット | - |
| --plugins | string[] | No | 使用するプラグイン | - |
| --config-file | string | No | 設定ファイルのパス | - |
| --env-name | string | No | 環境名 | BABEL_ENV \|\| NODE_ENV \|\| "development" |
| --root-mode | string | No | ルート解決モード（root/upward/upward-optional） | root |
| --source-type | string | No | ソースタイプ（script/module） | - |
| --no-babelrc | boolean | No | .babelrcの検索を無効化 | false |
| --ignore | string[] | No | 無視するglobパターン | - |
| --only | string[] | No | 対象とするglobパターン | - |
| --no-comments | boolean | No | コメントを出力しない | false |
| --retain-lines | boolean | No | 行番号を維持 | false |
| --compact | boolean \| "auto" | No | 空白を削減 | - |
| --minified | boolean | No | 最小化出力 | false |
| -s, --source-maps | boolean \| "inline" \| "both" | No | ソースマップ生成 | - |
| --source-map-target | string | No | ソースマップのファイル名 | - |
| --source-file-name | string | No | ソースマップのソースファイル名 | - |
| --source-root | string | No | ソースマップのルート | - |
| -x, --extensions | string[] | No | コンパイル対象の拡張子 | .js,.jsx,.es6,.es,.mjs,.cjs |
| --keep-file-extension | boolean | No | 拡張子を維持 | false |
| -w, --watch | boolean | No | ファイル監視モード | false |
| --skip-initial-build | boolean | No | 初回ビルドをスキップ | false |
| -o, --out-file | string | No | 単一出力ファイル | - |
| -d, --out-dir | string | No | 出力ディレクトリ | - |
| --relative | boolean | No | 入力相対パスを維持 | false |
| -D, --copy-files | boolean | No | 非コンパイルファイルをコピー | false |
| --include-dotfiles | boolean | No | ドットファイルを含める | false |
| --no-copy-ignored | boolean | No | 無視ファイルをコピーしない | false |
| --verbose | boolean | No | 詳細ログ出力 | false |
| --quiet | boolean | No | ログ出力を抑制 | false |
| --delete-dir-on-start | boolean | No | 開始時に出力ディレクトリを削除 | false |
| --out-file-extension | string | No | 出力ファイルの拡張子 | - |

### 入力データソース

- コマンドライン引数
- 標準入力（ファイル未指定時）
- ファイルシステム（ソースファイル/ディレクトリ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 変換後コード | ファイル/stdout | トランスパイル済みJavaScriptコード |
| ソースマップ | ファイル | .map形式のソースマップ |
| ログメッセージ | stderr | 進捗・エラー情報 |

### 出力先

- 指定された出力ファイル（-o, --out-file）
- 指定された出力ディレクトリ（-d, --out-dir）
- 標準出力（出力先未指定時）

## 処理フロー

### 処理シーケンス

```
1. CLIエントリーポイント (index.ts)
   └─ process.argvをパース
2. オプション解析 (options.ts)
   └─ commanderでオプションを解析
   └─ バリデーション
3. 処理分岐
   ├─ --out-dir指定時 → dirCommand (dir.ts)
   │      └─ ディレクトリ走査・各ファイル変換
   └─ それ以外 → fileCommand (file.ts)
          ├─ ファイル指定時 → walk & compile
          └─ ファイル未指定時 → stdin処理
4. @babel/coreでトランスパイル (util.ts)
5. 出力
   ├─ ファイル出力
   └─ ソースマップ出力
6. ウォッチモード（指定時）
   └─ ファイル変更を監視して再コンパイル
```

### フローチャート

```mermaid
flowchart TD
    A[babel CLI実行] --> B[parseArgv]
    B --> C{有効なオプション?}
    C -->|No| D[エラー出力・終了]
    C -->|Yes| E{--out-dir指定?}
    E -->|Yes| F[dirCommand]
    E -->|No| G[fileCommand]
    F --> H{ファイルごとに}
    H --> I[compile]
    I --> J[outputFileSync]
    J --> K{--watch?}
    K -->|Yes| L[watcher.watch]
    K -->|No| M[完了]
    G --> N{ファイル指定?}
    N -->|Yes| O[walk]
    N -->|No| P[stdin]
    O --> Q[compile & output]
    P --> R[transformRepl]
    R --> Q
    Q --> K
    L --> S[ファイル変更検出]
    S --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 出力先排他 | --out-fileと--out-dirは同時指定不可 | 両方指定時 |
| BR-02 | watch要件 | --watchは--out-fileまたは--out-dirが必要 | --watch指定時 |
| BR-03 | skip-initial-build要件 | --skip-initial-buildは--watchが必要 | --skip-initial-build指定時 |
| BR-04 | relative要件 | --relativeは--out-dirが必要 | --relative指定時 |
| BR-05 | 拡張子排他 | --keep-file-extensionと--out-file-extensionは同時指定不可 | 両方指定時 |
| BR-06 | verbose/quiet排他 | --verboseと--quietは同時指定不可 | 両方指定時 |
| BR-07 | stdin要件 | stdinコンパイルには-fまたは--no-babelrcが必要 | ファイル未指定時 |

### 計算ロジック

特になし

## データベース操作仕様

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル不存在 | 指定ファイルが存在しない | エラーメッセージ表示 |
| - | オプション競合 | 排他オプションの同時指定 | エラーメッセージで通知 |
| - | コンパイルエラー | Babelトランスパイル失敗 | --watch時は継続、それ以外は終了 |
| 1 | 一般エラー | コンパイルエラー等 | process.exitCode = 1 |
| 2 | 引数エラー | 無効なオプション | process.exitCode = 2 |

### リトライ仕様

- --watchモード時、エラー発生してもファイル監視を継続
- 次回ファイル変更時に再コンパイルを試行

## トランザクション仕様

該当なし（ファイル単位の独立処理）

## パフォーマンス要件

- 並列コンパイル：複数ファイルはPromise.allで並列処理
- debounce：ウォッチモードでのログ出力は100msでデバウンス
- 大量ファイル：ディレクトリ全体の走査と変換に対応

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

- ファイルシステムの読み書きを行うため、適切な権限設定が必要
- --delete-dir-on-startは出力ディレクトリを完全削除するため注意が必要

## 備考

- デフォルト拡張子は@babel/coreのDEFAULT_EXTENSIONSを使用
- ソースマップの自動検出と出力形式の決定

---

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

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

### 推奨読解順序

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

まず、コマンドラインオプションの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | options.ts | `packages/babel-cli/src/babel/options.ts` | CmdOptions型（169-190行目）、parseArgv関数（192-337行目） |

**読解のコツ**: commanderライブラリでオプション定義を行っている。各program.optionの定義がCLIオプションに対応する。

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

処理の起点となるファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-cli/src/babel/index.ts` | メインエントリーポイント（1-18行目） |

**主要処理フロー**:
1. **7行目**: parseArgvでコマンドライン引数を解析
2. **10行目**: --out-dirの有無でdirCommand/fileCommandを選択
3. **11-14行目**: コマンド実行とエラーハンドリング

#### Step 3: ディレクトリコマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | dir.ts | `packages/babel-cli/src/babel/dir.ts` | ディレクトリ変換処理（21-252行目） |

**主要処理フロー**:
- **25-86行目**: write関数 - 個別ファイルのコンパイル
- **95-108行目**: handleFile関数 - ファイル処理と非コンパイルファイルのコピー
- **110-133行目**: handle関数 - ファイル/ディレクトリの判定と処理
- **156行目**: ウォッチモードの有効化
- **179-251行目**: ウォッチモードのファイル変更監視

#### Step 4: ファイルコマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | file.ts | `packages/babel-cli/src/babel/file.ts` | 単一/複数ファイル変換処理（25-249行目） |

**主要処理フロー**:
- **29-83行目**: buildResult関数 - 複数ファイルの結合結果構築
- **94-122行目**: output関数 - 出力処理
- **124-140行目**: readStdin関数 - 標準入力の読み込み
- **142-151行目**: stdin関数 - stdinからの変換
- **153-208行目**: walk関数 - ファイル走査と変換

#### Step 5: ユーティリティを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | util.ts | `packages/babel-cli/src/babel/util.ts` | 共通ユーティリティ関数 |
| 5-2 | watcher.ts | `packages/babel-cli/src/babel/watcher.ts` | ファイル監視機能 |

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

```
babel (index.ts)
    │
    ├─ parseArgv (options.ts)
    │      └─ commander.program.parse
    │
    └─ dirCommand / fileCommand
           │
           ├─ dirCommand (dir.ts)
           │      ├─ write
           │      │      └─ util.compile → @babel/core
           │      ├─ handleFile
           │      │      └─ outputFileSync
           │      └─ watcher (watch時)
           │             └─ chokidar
           │
           └─ fileCommand (file.ts)
                  ├─ walk
                  │      ├─ util.compile → @babel/core
                  │      └─ output
                  ├─ stdin
                  │      └─ util.transformRepl
                  └─ watcher (watch時)
```

### データフロー図

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

CLI引数 ───────▶ parseArgv ───────▶ CmdOptions
                                         │
                                    ┌────┴────┐
                                    │         │
ソースファイル ───────▶ dirCommand ───────▶ 変換済みファイル群
                           │
stdin ───────▶ fileCommand ───────▶ 単一出力/stdout
                           │
                     @babel/core
                           │
                     ソースマップ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-cli/src/babel/index.ts` | ソース | CLIエントリーポイント |
| options.ts | `packages/babel-cli/src/babel/options.ts` | ソース | オプション解析 |
| dir.ts | `packages/babel-cli/src/babel/dir.ts` | ソース | ディレクトリ変換処理 |
| file.ts | `packages/babel-cli/src/babel/file.ts` | ソース | ファイル変換処理 |
| util.ts | `packages/babel-cli/src/babel/util.ts` | ソース | 共通ユーティリティ |
| watcher.ts | `packages/babel-cli/src/babel/watcher.ts` | ソース | ファイル監視 |
