# インフラ設計書

## 概要

本ドキュメントは、webpack（v5.105.3）プロジェクトのインフラ構成を記載する。webpackはオープンソースのJavaScriptモジュールバンドラーであり、npmパッケージとして配布されるNode.jsライブラリである。本プロジェクトはコンテナ化やクラウドインフラを持たず、GitHub上でのソースコード管理・CI/CD・パッケージ公開を中心としたインフラ構成となっている。

## システム構成

### 全体構成

webpackプロジェクトのインフラは以下の要素で構成される：

1. **ソースコード管理**: GitHub（`webpack/webpack` リポジトリ）
2. **CI/CDパイプライン**: GitHub Actions（テスト・リント・リリース・ベンチマーク）
3. **パッケージレジストリ**: npm（本番リリース）、pkg.pr.new（PRプレビュー公開）
4. **コードカバレッジ**: Codecov
5. **ベンチマーク**: CodSpeed
6. **依存関係管理**: Dependabot
7. **コミュニティ通知**: Discord Webhook
8. **Botによる自動化**: webpack-bot（open-bot.yaml）

本プロジェクトはライブラリであるため、Webサーバー・APサーバー・DBサーバー等のランタイムインフラは存在しない。

### サーバー構成

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| GitHub Actions Runner | CI/CDジョブ実行 | ubuntu-latest / windows-latest / macos-latest | ジョブ毎にオンデマンド |

※ 本プロジェクトはnpmライブラリであり、常時稼働するサーバーインフラは持たない。CI/CDはGitHub Actions上のエフェメラルランナーで実行される。

### ネットワーク構成

本プロジェクトは独自のネットワークインフラを持たない。以下の外部サービスとの通信が発生する：

- **GitHub ↔ GitHub Actions**: ワークフロー実行・成果物アップロード
- **GitHub Actions ↔ npm Registry**: パッケージ公開（`changeset publish`）
- **GitHub Actions ↔ Codecov**: カバレッジレポート送信
- **GitHub Actions ↔ CodSpeed**: ベンチマーク結果送信
- **GitHub Actions ↔ pkg.pr.new**: PRプレビューパッケージ公開
- **GitHub Actions ↔ Discord**: リリース通知（Webhook経由）

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Node.js | 10.x / 12.x / 14.x / 16.x / 18.x / 20.x / 22.x / 24.x / 25.x / lts/* / latest | ランタイム実行環境（テスト対象マトリクス） |
| Yarn | 1.22.22 | パッケージマネージャ（`packageManager`フィールドで固定） |
| Jest | 30.x（最新）/ 27.x（レガシーNode用） | テストフレームワーク |
| ESLint | 9.x | Lint（コード品質チェック） |
| Prettier | 3.x | コードフォーマッター |
| TypeScript | 5.x | 型チェック |
| cspell | 9.x | スペルチェック |
| Husky | 9.x | Git hooks管理 |
| lint-staged | 16.x | ステージングファイルのLint実行 |
| nyc / Istanbul | 18.x / 0.4.5 | コードカバレッジ計測 |
| Changesets | 2.x | リリース・バージョニング管理 |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| GitHub | ソースコード管理・Issue/PR管理 | Git / GitHub API |
| GitHub Actions | CI/CDパイプライン | ワークフローYAML |
| npm Registry | パッケージ公開 | `changeset publish`（OIDC認証） |
| pkg.pr.new | PRプレビューパッケージ公開 | `npx pkg-pr-new publish` |
| Codecov | コードカバレッジレポート | `codecov/codecov-action`（CODECOV_TOKEN） |
| CodSpeed | ベンチマークパフォーマンス測定 | `CodSpeedHQ/action`（CODSPEED_TOKEN） |
| Discord | リリースアナウンス通知 | Webhook（DISCORD_WEBHOOK） |
| Dependabot | 依存関係自動更新 | GitHub native integration |
| webpack-bot | Issue/PR自動管理 | open-bot.yaml設定 |

## スケーリング設計

本プロジェクトはnpmライブラリであり、ランタイムのスケーリングは不要である。

CI/CDのスケーリングについては以下の設計がなされている：

- **テストマトリクス並列化**: 統合テストはOS（ubuntu/windows/macos）× Node.jsバージョン（10.x〜25.x）× パート（a/b）のマトリクスで並列実行される
- **ベンチマークシャーディング**: ベンチマークは4つのシャード（1/4〜4/4）に分割して並列実行される
- **同時実行制御**: `concurrency` 設定により同一ワークフロー・同一ブランチでの重複実行がキャンセルされる（`cancel-in-progress: true`）
- **キャッシュ活用**: Jest結果キャッシュ・ESLintキャッシュ・Prettierキャッシュ・cspellキャッシュ・yarnキャッシュを活用してCI実行時間を削減

## 可用性設計

本プロジェクトはライブラリ配布であり、従来のサーバー可用性設計は該当しない。以下の観点で可用性が確保されている：

- **npm Registry**: npmの冗長インフラにより、パッケージのダウンロード可用性が担保される
- **CI/CD**: GitHub Actionsの可用性に依存。`fail-fast: false` 設定により、マトリクスの一部が失敗しても他のジョブは継続実行される
- **リリースプロセス**: Changesets による自動化されたリリースフローにより、手動操作によるヒューマンエラーを低減
- **依存関係の自動更新**: Dependabotによる週次の依存関係更新とnon-majorバージョンの自動マージ

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| ソースコード | Git分散リポジトリ | コミット毎 | 永続（Gitヒストリ） |
| npmパッケージ | npm Registry | リリース毎 | 永続（npmポリシーに依存） |
| CI/CDアーティファクト | GitHub Actions Artifacts | ジョブ実行毎 | GitHubデフォルト（90日） |
| カバレッジレポート | Codecov | テスト実行毎 | Codecovポリシーに依存 |

## 監視設計

本プロジェクトでは以下の監視・品質管理の仕組みが導入されている：

### CI/CDパイプライン監視
- **テスト実行結果**: GitHub Actionsのテストワークフローで lint → basic → unit → integration → test262 の順で品質チェック
- **カバレッジ監視**: Codecovにより、プロジェクト全体カバレッジ目標70%以上、パッチカバレッジ目標90%以上を監視（`codecov.yml`設定）
- **パフォーマンス監視**: CodSpeedによるベンチマーク（simulation + memory）でパフォーマンスリグレッションを検出

### セキュリティ監視
- **依存関係レビュー**: `dependency-review-action` によりPRの依存関係変更をライセンス・脆弱性の観点で自動レビュー
- **Dependabot**: 週次で依存関係の脆弱性・更新をチェック（npm / GitHub Actions / git submodule）

### コード品質監視
- **ESLint**: JavaScript/TypeScriptコードの静的解析
- **Prettier**: コードフォーマット整合性チェック
- **cspell**: スペルチェック
- **TypeScript**: 型チェック（複数バージョンで検証、TS 5.0互換性も確認）
- **lint-staged + Husky**: コミット時の自動チェック

## 備考

### Node.jsバージョン互換性
本プロジェクトは `engines: { node: ">=10.13.0" }` を宣言しており、Node.js 10.x以上の広範な互換性を維持している。CI/CDでは10.x〜25.xまでの幅広いNode.jsバージョンでテストを実行し、レガシー環境での互換性も確認している。レガシーNode.js（10.x/12.x/14.x/16.x）向けには、JestやdevDependenciesのバージョンをダウングレードして互換性を保っている。

### パッケージマネージャ
`packageManager`フィールドで Yarn 1.22.22 が固定されており、`corepack enable` による管理が可能である。`.npmrc` で `package-lock=false` が設定されており、npm lock fileは生成されない。

### リリースプロセス
Changesetsを用いた自動リリースフローを採用している。mainブランチへのpush時にリリースPRの作成またはnpmへの公開が自動実行される。リリース後にはDiscord Webhookでコミュニティへ通知される。npm公開にはOIDC認証（`id-token: write`権限）を使用している。

### シークレット管理
以下のシークレットがGitHub Actions環境で利用されている：
- `GITHUB_TOKEN`: GitHub API操作
- `CODECOV_TOKEN`: Codecovカバレッジ送信
- `CODSPEED_TOKEN`: CodSpeedベンチマーク送信
- `DISCORD_WEBHOOK`: Discordリリース通知
- `BOT_APP_ID` / `BOT_PRIVATE_KEY`: GitHub Appトークン生成（Dependabot自動マージ用）
