# バッチ設計書 20-ensure-npm-packages-exist

## 概要

本ドキュメントは、npmレジストリにパッケージが存在することを確認するCI/CDバッチ「ensure-npm-packages-exist」の設計を定義するものである。

### 本バッチの処理概要

ensure-npm-packages-existバッチは、Babelモノレポ内のすべての公開パッケージがnpmレジストリに存在することを検証するCI/CDジョブである。新しいパッケージが追加された場合、公開前に必要なセットアップ（パッケージの初期公開、OIDC設定）が完了しているかを確認する。

**業務上の目的・背景**：Babelプロジェクトでは、新しいパッケージを追加する際にnpmレジストリへの事前セットアップが必要である。GitHub ActionsからOIDC認証を使用してパッケージを公開するためには、事前にパッケージが存在し、適切なアクセス権限が設定されている必要がある。このバッチにより、リリース時に「パッケージが存在しない」というエラーを未然に防ぐことができる。

**バッチの実行タイミング**：GitHub Actions上でpushおよびpull_requestイベント発生時に自動実行される。yarn-validateジョブの完了後に実行される依存関係がある。

**主要な処理内容**：
1. リポジトリのチェックアウト
2. Node.js最新版のセットアップと依存関係のインストール
3. ワークスペース内の非プライベートパッケージを列挙
4. 各パッケージがnpmレジストリに存在するかAPIで確認
5. 存在しないパッケージがある場合、エラーを報告

**前後の処理との関連**：本バッチはyarn-validateジョブの成功を前提とする。テスト結果の合否のみを報告し、他のジョブへの出力はない。

**影響範囲**：本バッチは検証のみを行い、npmレジストリやソースコードの変更は行わない。パッケージが存在しない場合はCIが失敗となり、PRのマージがブロックされる。

## バッチ種別

検証 / パッケージ存在確認

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | GitHub Actions（push/pull_request） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| yarn-validate完了 | Yarn依存関係の検証が完了していること |
| ネットワーク接続 | npmレジストリAPIへのアクセスが可能であること |

### 実行可否判定

yarn-validateジョブが成功した場合のみ実行される（needs: yarn-validate）。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --check-only | フラグ | No | true | 確認のみで自動作成しない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| yarn workspaces list | JSON | ワークスペース内のパッケージ一覧 |
| registry.npmjs.org | API | npmレジストリ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 検証結果・エラー詳細 |
| GitHub Actions Log | ログ | ジョブ実行ログ |

### 出力ファイル仕様

本バッチはファイル出力を行わない。

## 処理フロー

### 処理シーケンス

```
1. リポジトリチェックアウト
   └─ actions/checkout@v4を使用
2. Node.js環境セットアップ
   └─ Node.js 25.6.1をセットアップ、Yarnキャッシュを有効化
3. 依存関係インストール
   └─ yarn installを実行
4. パッケージ存在確認スクリプト実行
   └─ node ./scripts/ensure-packages-exist.ts --check-onlyを実行
5. パッケージ一覧取得
   └─ yarn workspaces list --no-private --jsonで非プライベートパッケージを列挙
6. 各パッケージの存在確認
   └─ npmレジストリAPIでパッケージの存在を確認
7. 結果報告
   └─ 存在しないパッケージがある場合はエラー終了
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[リポジトリチェックアウト]
    B --> C[Node.js環境セットアップ]
    C --> D[yarn install]
    D --> E[ensure-packages-exist.ts 実行]
    E --> F[yarn workspaces list]
    F --> G[パッケージループ開始]
    G --> H[npmレジストリAPI呼び出し]
    H --> I{パッケージ存在?}
    I -->|存在| J[次のパッケージへ]
    I -->|存在しない| K[失敗リストに追加]
    J --> L{全パッケージ確認完了?}
    K --> L
    L -->|未完了| G
    L -->|完了| M{失敗パッケージあり?}
    M -->|なし| N[成功終了]
    M -->|あり| O[エラー出力]
    O --> P[失敗終了]
```

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

### 操作別データベース影響一覧

本バッチはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| PACKAGE_NOT_FOUND | パッケージ未存在 | npmレジストリにパッケージがない | メンテナーがパッケージを作成してOIDC設定 |
| REGISTRY_ERROR | APIエラー | npmレジストリAPIエラー | ネットワークを確認、リトライ |
| NETWORK_ERROR | ネットワークエラー | 接続タイムアウト | ネットワーク状態を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. GitHub Actionsのログを確認し、存在しないパッケージを特定する
2. メンテナーがnpmにログインし、手動でパッケージを作成する
3. npm.comでOIDC発行設定を行う（Publisher: GitHub Actions, Repository: babel/babel, Workflow: release.yml）
4. または`node scripts/ensure-packages-exist.ts`を対話モードで実行して自動セットアップ

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データ操作なし） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約100パッケージ |
| 目標処理時間 | 5分以内 |
| メモリ使用量上限 | 4GB（GitHub Actionsランナーのデフォルト） |
| API並列度 | 10（p-limitによる制限） |

## 排他制御

同一ブランチに対する同時実行は、GitHub Actionsのconcurrencyグループ設定により制御される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | ジョブ名 |
| チェックログ | 各パッケージ確認時 | パッケージ名、存在/不在 |
| 成功ログ | 全パッケージ存在時 | "All packages exist on npm :)" |
| エラーログ | パッケージ不在時 | 不在パッケージ一覧、セットアップ手順 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 10分超過 | GitHub Actions UI |
| 不在パッケージ数 | 1件以上 | GitHub Actions UI |

## 備考

- `--check-only`フラグを指定すると確認のみで自動作成は行わない（CIではこのモードで実行）
- フラグなしで実行すると、メンテナーがnpmにログインしている場合にパッケージを自動作成できる
- `p-limit(10)`により、npmレジストリAPIへのリクエストは並列度10に制限される
- OIDC設定の詳細：Publisher: GitHub Actions、Organization: babel、Repository: babel、Workflow filename: release.yml、Environment name: npm
- 新しいパッケージを追加する際は、このチェックが通過するようにセットアップが必要
- yarn workspaces list --no-privateで、private: trueのパッケージは除外される
