# インフラ設計書

## 概要

本ドキュメントは、Babelプロジェクト（JavaScriptトランスパイラ）のインフラストラクチャ設計を記載する。BabelはOSSプロジェクトであり、従来のWebアプリケーションとは異なり、サーバーレスなCI/CD中心のインフラ構成を採用している。主にGitHub Actions、CircleCI、および各種SaaSサービスを活用したクラウドネイティブな開発・配布インフラとなっている。

## システム構成

### 全体構成

Babelのインフラは以下の3層で構成される：

1. **ソースコード管理層**: GitHub（babel/babel リポジトリ）
2. **CI/CD層**: GitHub Actions（主要）、CircleCI（補助）
3. **配布・公開層**: npm Registry、pkg.pr.new、Codecov、CodeSandbox

本プロジェクトはNPMパッケージとして配布されるライブラリであり、アプリケーションサーバーやデータベースサーバーは保有しない。

### サーバー構成

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| GitHub Actions Runner (ubuntu-latest) | CI/CDジョブ実行 | GitHub提供標準ランナー | 動的スケーリング |
| GitHub Actions Runner (windows-latest) | Windows環境テスト | GitHub提供標準ランナー | 動的スケーリング |
| GitHub Actions Runner (macos-latest) | macOS環境テスト | GitHub提供標準ランナー | 動的スケーリング |
| CircleCI Executor (cimg/node:current) | babel-standalone ビルド | Docker (Node.js最新版) | 動的スケーリング |

### ネットワーク構成

- GitHub Actions ランナー: GitHub管理のクラウドネットワーク内で実行
- 外部接続: npm Registry、GitHub API、Codecov API へのHTTPS通信
- Verdaccio（E2Eテスト用）: ローカルネットワーク（localhost:4873）でテスト時に一時起動

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Node.js | 25.6.1（最新）、24、22、20 | ビルド・テスト実行環境 |
| Yarn | 4.10.3 | パッケージマネージャー |
| Jest | 30.1.1 | テストフレームワーク |
| c8 | 10.0.0 | コードカバレッジ |
| Gulp | 5.0.1 | ビルドタスクランナー |
| Rollup | 4.18.0 | バンドラー |
| TypeScript | 5.9.3 | 型チェック・コンパイル |
| ESLint | 10.0.0 | コード品質チェック |
| Prettier | 3.8.1 | コードフォーマッター |
| Verdaccio | 最新 | E2Eテスト用ローカルnpmレジストリ |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| GitHub | ソースコード管理、CI/CD、Issue管理、PR管理 | HTTPS/GitHub API |
| npm Registry | パッケージ公開・配布 | HTTPS (npm publish) |
| CircleCI | babel-standalone ビルド・アーティファクト保存 | HTTPS/CircleCI API |
| Codecov | コードカバレッジレポート収集・可視化 | codecov/codecov-action v5 |
| CodeSandbox | オンラインサンドボックス環境 | CI統合 (ci.json) |
| Gitpod | クラウド開発環境 | .gitpod.yml 設定 |
| pkg.pr.new | PRごとのパッケージプレビュー公開 | HTTPS |
| Renovate | 依存関係自動更新 | GitHub App |

## スケーリング設計

### CI/CD スケーリング

Babelプロジェクトでは以下のスケーリング戦略を採用：

1. **並列ジョブ実行**
   - テストマトリクス: Node.js 20, 22, 24, 25.6.1 で並列テスト
   - OS マトリクス: ubuntu-latest, windows-latest, macos-latest で並列テスト
   - test262 テスト: 8 チャンクに分割して並列実行

2. **キャッシュ活用**
   - Yarn キャッシュ: `~/.yarn/berry/cache` を CircleCI でキャッシュ
   - GitHub Actions: `actions/setup-node` の cache 機能活用

3. **コンカレンシー制御**
   ```yaml
   concurrency:
     group: ${{ github.workflow }}-${{ github.ref }}
     cancel-in-progress: true
   ```
   同一ブランチの実行中ワークフローをキャンセルし、リソースを最適化

### アーティファクト管理

- ビルドアーティファクトは `actions/upload-artifact` で一時保存（retention-days: 5）
- 後続ジョブで `actions/download-artifact` を使用して共有

## 可用性設計

### CI/CD 可用性

1. **ワークフロー冗長性**
   - 主要CI: GitHub Actions
   - 補助CI: CircleCI（babel-standalone ビルド専用）

2. **ジョブ失敗戦略**
   ```yaml
   strategy:
     fail-fast: false
   ```
   一つのジョブが失敗しても他のジョブを継続実行

3. **リトライ機構**
   - GitHub Actions の標準リトライ機能を活用

### リリース可用性

1. **デュアルトリガー対応**
   - タグプッシュ (`v*`) によるリリース
   - workflow_dispatch による手動リリース

2. **段階的リリース**
   - ログ確認 -> npm公開 -> GitHub Release -> main ブランチ更新

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| ソースコード | Git分散リポジトリ | 各コミット時 | 永続 |
| ビルドアーティファクト | actions/upload-artifact | ビルド毎 | 5日間 |
| テスト結果 (test262) | actions/upload-artifact | テスト毎 | 30日間 |
| Verdaccio ワークスペース | actions/upload-artifact | E2Eテスト毎 | 1日間 |
| CircleCI アーティファクト | CircleCI store_artifacts | ビルド毎 | CircleCI 標準保持期間 |

## 監視設計

### CI/CD 監視

1. **GitHub Actions ステータス**
   - プルリクエストに自動ステータスチェック表示
   - ワークフロー実行結果の可視化

2. **コードカバレッジ監視**
   - Codecov によるカバレッジレポート
   - ターゲットカバレッジ: 90.0%
   - パッチカバレッジ: 無効化

3. **依存関係監視**
   - Renovate による自動依存関係更新
   - dependencyDashboardApproval による承認制御

### アラート・通知

| 監視項目 | 通知先 | 条件 |
| --- | --- | --- |
| CI 失敗 | GitHub PR ステータス | ジョブ失敗時 |
| セキュリティアラート | GitHub Security タブ | 脆弱性検出時 |
| Issue/PR リマインダー | issue-triage.yml, reminders.yml | スケジュールベース |

## 環境構成

### 開発環境

| 環境名 | 用途 | 構成 |
| --- | --- | --- |
| ローカル開発 | 開発者PC | Node.js + Yarn + Make |
| Gitpod | クラウド開発 | Gitpod プリビルド対応 |
| CodeSandbox | サンドボックス | Node.js 14（ci.json設定） |

### CI/CD 環境変数

| 変数名 | 用途 |
| --- | --- |
| `BABEL_ENV` | Babel 環境設定 (test, test-legacy) |
| `BABEL_COVERAGE` | カバレッジ収集有効化 |
| `BABEL_9_BREAKING` | Babel 9 破壊的変更フラグ |
| `STRIP_BABEL_VERSION_FLAG` | バージョンフラグ除去 |
| `FORCE_COLOR` | 色付き出力強制 |
| `YARN_ENABLE_HARDENED_MODE` | Yarn セキュリティモード |
| `YARN_ENABLE_SCRIPTS` | postinstall スクリプト制御 |
| `YARN_NODE_LINKER` | リンカー設定 (pnp) |

## ワークスペース構成

Yarn ワークスペースによるモノレポ構成：

```
babel-main/
├── codemods/*          # コードモッドパッケージ
├── eslint/*            # ESLint 関連パッケージ
├── packages/*          # コアパッケージ群（150+）
├── test/esm            # ESM テスト
├── test/runtime-integration/*  # ランタイム統合テスト
└── benchmark           # ベンチマーク
```

## 備考

### プロジェクト特性

- OSSプロジェクトのため、従来のWebアプリケーションインフラとは構成が異なる
- サーバーレスCI/CDを中心としたクラウドネイティブ構成
- 150以上のパッケージを持つ大規模モノレポ

### 継続的改善

- Node.js バージョンは定期的に最新版へ更新（現在 25.6.1）
- Babel 8 から Babel 9 への移行に伴うCI/CD並行実行
- test262、TypeScript、Flow の外部パーサーテスト継続実行

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

- `YARN_ENABLE_HARDENED_MODE: true` による強化モード
- npm publish 時の `id-token: write` 権限（npm provenance対応）
- `pull_request_target` ワークフローでのセキュリティ考慮
