# インフラ設計書

## 概要

本ドキュメントは、Jest（JavaScriptテスティングフレームワーク）プロジェクトのインフラ構成を定義します。Jestはクライアントサイドで実行されるNPMパッケージであり、従来のサーバーインフラは持ちません。本設計書では、開発・CI/CD・ドキュメントホスティングに関するインフラ構成を記載します。

## システム構成

### 全体構成

Jestは以下のインフラ要素で構成されます：

1. **CI/CD基盤**: GitHub Actions（テスト、ビルド、リリース自動化）
2. **ドキュメントホスティング**: Netlify（jestjs.ioドキュメントサイト）
3. **パッケージレジストリ**: npm Registry（パッケージ配布）
4. **ソースコード管理**: GitHub（リポジトリホスティング）
5. **カバレッジレポート**: Codecov（コードカバレッジ可視化）

### サーバー構成

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| GitHub Actions Runner (Ubuntu) | CI/CDテスト実行（メイン） | ubuntu-latest（2コア以上、自動スケール） | 4シャード並列 |
| GitHub Actions Runner (macOS) | CI/CDテスト実行（macOS互換性確認） | macos-latest（自動スケール） | 3シャード並列 |
| GitHub Actions Runner (Windows) | CI/CDテスト実行（Windows互換性確認） | windows-latest（自動スケール） | 4シャード並列 |
| Netlify Build Environment | ドキュメントサイトビルド | Node 20、メモリ4GB（NODE_OPTIONS） | オンデマンド |

### ネットワーク構成

Jestはライブラリプロジェクトのため、独自のネットワークインフラは持ちません。CI/CD実行時は以下のネットワーク接続が使用されます：

- **GitHub Actions**: GitHub提供のホステッド環境（パブリックインターネット経由）
- **Netlify**: Netlify CDN経由のグローバル配信
- **npm Registry**: HTTPS経由のパッケージ公開・取得

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Node.js | 18.x / 20.x / 22.x / 24.x（マトリクステスト） | JavaScript実行環境 |
| Yarn | 4.12.0（Berry） | パッケージマネージャー |
| Lerna-lite | ^4.3.0 | モノレポ管理 |
| TypeScript | ^5.8.3 | 型チェック・ビルド |
| Webpack | ^5.68.0 | バンドル処理 |
| Babel | ^7.27.4 | トランスパイル |
| Docusaurus | ^3.0.0 | ドキュメントサイト生成 |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| GitHub | ソースコード管理、Issue/PR管理 | Git/HTTPS |
| GitHub Actions | CI/CD自動化 | GitHub提供環境 |
| Netlify | ドキュメントサイトホスティング | Webhook連携（Git push） |
| npm Registry | パッケージ公開・配布 | npm publish（Lerna経由） |
| Codecov | コードカバレッジレポート | GitHub Actions連携 |
| Crowdin | 多言語翻訳管理 | CLI連携 |
| Open Collective | 寄付・スポンサー管理 | 外部リンク |

## スケーリング設計

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

- **シャーディング**: テスト実行を複数シャードに分割（Ubuntu: 4シャード、macOS: 3シャード、Windows: 4シャード）
- **並列実行**: CPUコア数に応じたmax-workers設定（`SimenB/github-actions-cpu-cores`で動的取得）
- **同時実行制御**: `concurrency`グループによる重複実行キャンセル
- **リトライ**: テスト失敗時の自動リトライ（最大3回、タイムアウト10分）

### ドキュメントサイト スケーリング

- **Netlify CDN**: グローバルCDNによる自動スケーリング
- **ビルドキャッシュ**: `netlify-plugin-cache`による増分ビルド最適化
- **条件付きビルド**: `website/`、`docs/`変更時のみ本番ビルド実行

## 可用性設計

### CI/CD 可用性

- **マルチプラットフォームテスト**: Ubuntu/macOS/Windowsでの並列テストにより、単一プラットフォーム障害時も継続可能
- **マルチNodeバージョン**: Node.js 18.x/20.x/22.x/24.xでのテストにより、バージョン互換性を確保
- **Nightly Build**: 毎日12:00 UTC実行による早期障害検知（`nightly.yml`）
- **失敗通知**: Nightlyビルド失敗時のIssue自動作成（`jayqi/failed-build-issue-action`）

### ドキュメントサイト 可用性

- **Netlify SLA**: Netlifyの標準SLAに準拠
- **デプロイプレビュー**: PRごとのプレビューデプロイで本番影響を最小化

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| ソースコード | Git分散リポジトリ | リアルタイム（push毎） | 永続 |
| npm パッケージ | npm Registry | リリース毎 | 永続（non-deprecate） |
| ドキュメントサイト | Netlify Deploy | デプロイ毎 | Netlify保持ポリシーに準拠 |
| CI/CDログ | GitHub Actions Logs | 実行毎 | 90日（GitHub標準） |

## 監視設計

### CI/CD 監視

| 監視項目 | 方式 | 閾値/条件 |
| --- | --- | --- |
| テスト失敗 | GitHub Actions Status | 任意のジョブ失敗時 |
| リーク検出 | jest-leak テスト | メモリリーク検出時（`--detectLeaks`） |
| カバレッジ低下 | Codecov | 設定閾値未満時 |
| Nightlyビルド失敗 | Issue自動作成 | 失敗時（`failure()`条件） |
| Stale Issue/PR | actions/stale | 30日/90日非アクティブ |

### ドキュメントサイト 監視

| 監視項目 | 方式 | 閾値/条件 |
| --- | --- | --- |
| ビルド失敗 | Netlify通知 | ビルドエラー時 |
| デプロイ状況 | Netlify Dashboard | デプロイ完了/失敗 |

## 環境変数設計

### CI/CD 環境変数

| 変数名 | 用途 | 設定場所 |
| --- | --- | --- |
| `GITHUB_TOKEN` | GitHub API認証 | GitHub Actions自動提供 |
| `CODECOV_TOKEN` | Codecovアップロード認証 | GitHub Secrets |
| `JEST_JASMINE` | jest-jasmine2ランナー有効化 | ワークフロー内 |

### Netlify 環境変数

| 変数名 | 値 | 用途 |
| --- | --- | --- |
| `NODE_VERSION` | 20 | Node.jsバージョン指定 |
| `NODE_OPTIONS` | --max_old_space_size=4096 | メモリ上限拡張 |
| `YARN_ENABLE_GLOBAL_CACHE` | true | Yarnグローバルキャッシュ有効化 |
| `YARN_GLOBAL_FOLDER` | /opt/buildhome/.yarn_cache | キャッシュディレクトリ |
| `YARN_CACHE_FOLDER` | /opt/buildhome/.yarn_cache | キャッシュディレクトリ |
| `YARN_VERSION` | 3.6.4 | Yarnバージョン（Netlify用） |

## CI/CDパイプライン構成

### メインCI（nodejs.yml）

トリガー: `push`（main）、`pull_request`、`merge_group`

1. **Yarn Cache準備**: Ubuntu/macOS/Windows各環境でキャッシュ準備
2. **TypeScript互換性チェック**: TypeScript 5.4+での互換性検証
3. **静的チェック**: Lint、Typecheck、Prettier、Changelog、Copyright Headers、Constraints
4. **テスト実行**: 3プラットフォーム x 複数シャードでのマトリクステスト
5. **リーク検出**: メモリリーク検出テスト
6. **カバレッジ収集**: 4シャードでのカバレッジ収集、Codecovアップロード

### Nightlyビルド（nightly.yml）

トリガー: 毎日12:00 UTC、手動実行

- Node.js Nightlyバージョンでのテスト実行
- 失敗時のIssue自動作成

### Stale管理（close-stale.yml）

トリガー: 毎時

- 30日非アクティブIssueのStale化
- 90日非アクティブPRのStale化
- 1年非アクティブIssue/PRのクローズ

## 備考

### プロジェクト特性

Jestはサーバーサイドアプリケーションではなく、Node.js上で動作するJavaScriptテスティングフレームワーク（ライブラリ）です。そのため：

- 本番運用サーバーは存在しない
- ユーザーはローカル環境またはCI環境でJestを実行
- インフラはCI/CD自動化とドキュメントホスティングに限定

### モノレポ構成

- 55個のパッケージを`packages/`配下で管理
- Lerna-liteによるバージョン管理
- Yarn Workspacesによる依存関係管理

### サポートNode.jsバージョン

`package.json`のengines設定:
```
^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0
```
