# インフラ設計書

## 概要

本ドキュメントは、Prettierプロジェクトのインフラストラクチャ構成を記載した設計書です。Prettierはオープンソースのコードフォーマッターであり、主にnpmパッケージとして配布されています。本プロジェクトはコンテナ化やサーバーインフラを持たず、CI/CDパイプライン、静的サイトホスティング、およびパッケージ配布を中心としたインフラ構成となっています。

## システム構成

### 全体構成

Prettierプロジェクトは以下のコンポーネントで構成されています：

1. **ソースコード管理**: GitHub（prettier/prettier リポジトリ）
2. **CI/CDパイプライン**: GitHub Actions
3. **ドキュメントサイト**: Netlify（静的サイトホスティング）
4. **パッケージレジストリ**: npm（パッケージ配布）
5. **セキュリティ分析**: GitHub CodeQL
6. **コードカバレッジ**: Codecov

### サーバー構成

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| GitHub Actions Runner | CI/CDワークフロー実行 | ubuntu-latest, macos-latest, windows-latest | オンデマンド |
| Netlify CDN | ドキュメントサイト配信 | マネージドサービス | N/A |

**備考**: 本プロジェクトはnpmライブラリとして配布されるため、専用のアプリケーションサーバーやデータベースサーバーは存在しません。

### ネットワーク構成

本プロジェクトはサーバーレスアーキテクチャを採用しており、専用のネットワーク構成は持ちません。以下の外部サービスとの通信が発生します：

- **GitHub Actions**: ビルド・テスト実行時にGitHub APIおよびnpm registryと通信
- **Netlify**: ドキュメントサイトのビルド・デプロイ時にGitHubリポジトリと連携
- **Codecov**: テストカバレッジレポートのアップロード

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Node.js | >= 20（開発）/ >= 14（本番動作保証） | JavaScript実行環境 |
| Yarn | 4.12.0 | パッケージマネージャー |
| esbuild | 0.27.2 | バンドラー |
| Jest | 30.2.0 | テストフレームワーク |
| ESLint | 9.39.2 | 静的解析ツール |
| TypeScript | 5.9.3 | 型チェック |
| Docusaurus | 3.9.2 | ドキュメントサイト生成 |
| Vite | 7.3.1 | フロントエンドビルドツール（Playground） |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| GitHub | ソースコード管理、CI/CD | HTTPS / Git |
| GitHub Actions | CI/CDパイプライン実行 | GitHub API |
| Netlify | ドキュメントサイトホスティング | Webhook / Git連携 |
| npm Registry | パッケージ配布 | HTTPS |
| Codecov | コードカバレッジレポート | HTTPS / GitHub連携 |
| pkg-pr-new | PRプレビューリリース | npm公開 |

## CI/CD パイプライン設計

### ワークフロー一覧

| ワークフロー名 | トリガー | 目的 |
| --- | --- | --- |
| `prod-test.yml` | push（main, next, v*, patch-release）, pull_request | 本番ビルド・テスト |
| `dev-test.yml` | push（main, next, v*, patch-release）, pull_request | 開発テスト・カバレッジ |
| `lint.yml` | push（main, next, v*, patch-release）, pull_request | 静的解析・フォーマットチェック |
| `codeql.yml` | push, pull_request | セキュリティ脆弱性分析 |
| `check-sizes.yml` | pull_request | バンドルサイズ監視 |
| `autofix.yml` | pull_request | 自動修正（Prettier共有ワークフロー） |
| `bundler-friendly.yml` | schedule（毎週日曜）, pull_request | バンドラー互換性テスト |

### テストマトリックス

**本番テスト（prod-test.yml）**:

| OS | Node.js バージョン |
| --- | --- |
| ubuntu-latest | 14, 16, 18, 20, 22, 24, 25 |
| macos-latest | 24 |
| macos-15-intel | 14 |
| windows-latest | 14, 24 |

**ブラウザテスト**:
- Chrome（Linux, Windows）
- Firefox（Linux, Windows）
- バンドル形式：ESM, UMD

### ビルドプロセス

1. **Checkout**: ソースコード取得
2. **Setup Node.js**: Node.js環境セットアップ（Yarnキャッシュ有効）
3. **Install Dependencies**: `yarn install --immutable`
4. **Build Package**: `yarn build --clean`
5. **Upload Artifact**: ビルド成果物をGitHub Artifactsにアップロード

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

| アーティファクト名 | 内容 | 用途 |
| --- | --- | --- |
| `dist` | ビルド済みパッケージ | テスト実行、プレビューリリース |

## スケーリング設計

本プロジェクトはnpmパッケージとして配布されるライブラリであり、ユーザー環境で実行されます。そのため、サーバーサイドのスケーリング要件はありません。

**CI/CDスケーリング**:
- GitHub Actions のマトリックスビルドにより、複数OS・Node.jsバージョンで並列テスト実行
- 同時実行制御（concurrency）により、同一ブランチの重複ワークフローをキャンセル

## 可用性設計

本プロジェクトのインフラは完全にマネージドサービスに依存しています：

| コンポーネント | 可用性担保 |
| --- | --- |
| GitHub | GitHub SLA（99.9%以上） |
| GitHub Actions | GitHub Actions SLA |
| Netlify | Netlify SLA（99.9%以上） |
| npm Registry | npm SLA |

**冗長構成**:
- ソースコードはGitの分散バージョン管理により冗長化
- ドキュメントサイトはNetlify CDNにより地理的に分散配信

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| ソースコード | Git分散リポジトリ | コミット毎 | 永続 |
| ビルドアーティファクト | GitHub Artifacts | ワークフロー実行毎 | 90日（デフォルト） |
| ドキュメントサイト | Netlify Deploys | デプロイ毎 | 無期限（無料プラン制限あり） |

## 監視設計

| 監視対象 | 監視方式 | アラート |
| --- | --- | --- |
| CI/CDパイプライン | GitHub Actions ステータス | GitHub通知、PRステータスチェック |
| セキュリティ脆弱性 | CodeQL分析 | GitHub Security Alerts |
| 依存関係 | Renovate、Dependency Review | PR自動作成、PRブロック |
| バンドルサイズ | compressed-size-action | PRコメント |
| コードカバレッジ | Codecov | Codecovレポート |

## セキュリティ設計

### 権限管理（GitHub Actions）

| ワークフロー | 権限 |
| --- | --- |
| 標準ワークフロー | `contents: read` |
| CodeQL | `contents: read`, `security-events: write`, `actions: read` |
| Check Sizes | `contents: read`, `pull-requests: write` |

### セキュリティスキャン

- **CodeQL**: JavaScriptコードの静的セキュリティ分析
- **Dependency Review**: 依存関係の脆弱性チェック（PRのみ）
- **Renovate**: 依存関係の自動更新

## 環境設定

### Netlify環境変数

| 変数名 | 値 | 説明 |
| --- | --- | --- |
| `NODE_VERSION` | `lts/*` | Node.js LTS バージョン使用 |
| `YARN_VERSION` | `1.22.22` | Yarn バージョン指定 |

### CI/CD環境変数

| 変数名 | 用途 |
| --- | --- |
| `NODE_ENV` | 実行環境識別（production/development） |
| `FULL_TEST` | フルテスト実行フラグ |
| `ENABLE_CODE_COVERAGE` | カバレッジ収集フラグ |
| `TEST_RUNTIME` | テスト実行環境（node/browser） |
| `TEST_RUNTIME_BROWSER` | ブラウザ種別（chrome/firefox） |
| `TEST_BUNDLE_FORMAT` | バンドル形式（esm/umd） |
| `CODECOV_TOKEN` | Codecov認証トークン（シークレット） |

## 備考

### プロジェクト特性

- Prettierはクライアントサイドで動作するnpmパッケージであり、サーバーインフラは不要
- Dockerコンテナ、Kubernetes、Terraformなどのインフラコード（IaC）は使用されていない
- 全てのインフラはマネージドサービス（GitHub、Netlify、npm）に依存

### 開発環境要件

- Node.js >= 20（開発時）
- Yarn 4.12.0（packageManagerフィールドで指定）
- 対応ブラウザ: ">0.5%, not dead, not op_mini all"

### 本番動作保証

- Node.js >= 14（本番環境での最小動作バージョン）
- レガシーNode.js（14, 16）向けにJestダウングレード対応あり
