# バッチ設計書 21-e2e-publish

## 概要

本ドキュメントは、BabelプロジェクトにおけるE2Eテスト用ローカルVerdaccioレジストリへのパッケージ公開バッチ（e2e-publish）の設計仕様を記載する。

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

このバッチは、Babelの全パッケージをローカルのVerdaccioレジストリに公開し、後続のE2Eテストで使用可能な状態にする処理を行う。

**業務上の目的・背景**：Babelは多数のnpmパッケージで構成されるモノレポ構造を持つ。実際のnpmレジストリに公開する前に、ローカル環境でパッケージの動作検証を行う必要がある。本バッチは、Verdaccioというローカルnpmレジストリを起動し、Babelの全パッケージを一時的なバージョンで公開することで、E2Eテスト環境を構築する。これにより、公開前の品質保証と各種フレームワークとの統合テストが可能となる。

**バッチの実行タイミング**：GitHub Actionsワークフローにおいて、mainブランチへのpushまたはプルリクエスト発生時に自動実行される。E2Eテストジョブの前提条件として最初に実行される。

**主要な処理内容**：
1. 一時的なGitブランチを作成し、E2Eテスト用のGit設定を初期化
2. プロジェクトの依存関係をインストール（yarn）
3. Verdaccioローカルレジストリを起動
4. パッケージバージョンを自動計算（現行バージョンのパッチ番号を+1）
5. 全Babelパッケージをローカルレジストリに公開（make publish-test）
6. 公開されたパッケージをtarアーカイブとして保存

**前後の処理との関連**：本バッチは他の全E2Eテストバッチ（e2e-babel、e2e-create-react-app等）の前提条件となる。後続のテストは、本バッチで作成されたverdaccio-workspaceアーティファクトをダウンロードして使用する。

**影響範囲**：ローカルVerdaccioレジストリ（/tmp/verdaccio-workspace）、GitHub Actionsアーティファクトストレージ。本番環境やnpmレジストリには影響しない。

## バッチ種別

パッケージ公開 / E2Eテスト準備

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（push/プルリクエスト時） |
| 実行時刻 | 随時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | GitHub Actions（push to main / pull_request） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js 25.6.1がインストールされていること |
| Yarn | Yarnパッケージマネージャが利用可能であること |
| Git | Gitがインストールされ、リポジトリがクローンされていること |
| ネットワーク | npmレジストリ（npmjs.org）へのアクセスが可能であること |

### 実行可否判定

- mainブランチへのpush、またはプルリクエストが発生した場合に自動実行
- 同一ワークフローの同一refに対する実行が重複する場合、前の実行をキャンセル

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| fetch-depth | number | No | 0 | Gitリポジトリの取得深度（全履歴） |
| node-version | string | No | 25.6.1 | 使用するNode.jsバージョン |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| package.json | JSON | プロジェクトルートのパッケージ設定（バージョン情報取得用） |
| packages/* | ディレクトリ | 公開対象の各Babelパッケージ |
| verdaccio-config.yml | YAML | Verdaccioレジストリ設定ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| /tmp/verdaccio-workspace/storage | ディレクトリ | Verdaccioストレージ（公開パッケージ） |
| /tmp/verdaccio-workspace.tar | tar | パッケージアーカイブ |
| verdaccio-workspace（アーティファクト） | tar | GitHub Actionsアーティファクト |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | verdaccio-workspace.tar |
| 出力先 | /tmp |
| 文字コード | バイナリ |
| 保持期間 | 1日（retention-days: 1） |

## 処理フロー

### 処理シーケンス

```
1. Git初期化
   └─ E2Eテスト用の一時ブランチを作成、Git設定を変更
2. 依存関係インストール
   └─ yarn を実行して全パッケージの依存関係をインストール
3. Verdaccio起動
   └─ ローカルレジストリを起動し、レジストリURLを環境変数に設定
4. バージョン計算
   └─ package.jsonから現行バージョンを取得し、パッチ番号を+1
5. パッケージ公開
   └─ make publish-testで全パッケージをVerdaccioに公開
6. アーカイブ作成
   └─ /tmp/verdaccio-workspaceをtarでパック
7. アーティファクト保存
   └─ GitHub Actionsのupload-artifactでアーカイブを保存
8. クリーンアップ
   └─ Verdaccioを停止、Gitブランチを削除
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[コードチェックアウト]
    B --> C[Node.js環境セットアップ]
    C --> D[E2E Git初期化]
    D --> E[yarn依存関係インストール]
    E --> F[Verdaccio起動]
    F --> G[レジストリログイン]
    G --> H[バージョン計算]
    H --> I[make publish-test実行]
    I --> J[tarアーカイブ作成]
    J --> K[アーティファクトアップロード]
    K --> L[クリーンアップ]
    L --> M[バッチ終了]
```

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

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ERR_YARN | 依存関係エラー | yarn installが失敗 | ログを確認し、パッケージの依存関係を修正 |
| ERR_VERDACCIO | レジストリエラー | Verdaccio起動失敗 | ポート4873の使用状況を確認 |
| ERR_PUBLISH | 公開エラー | パッケージ公開失敗 | パッケージ設定を確認 |
| ERR_GIT | Git操作エラー | ブランチ作成/削除失敗 | Git状態を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（GitHub Actions側で再実行可能） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. GitHub Actionsのログを確認し、エラー発生箇所を特定
2. 必要に応じてワークフローを手動で再実行
3. Verdaccio関連のエラーの場合、ローカルでpublish-local.shを実行して再現確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（npmパッケージ公開はアトミック） |
| コミットタイミング | 各パッケージ公開完了時 |
| ロールバック条件 | エラー発生時はcleanup関数でクリーンアップ |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約150パッケージ |
| 目標処理時間 | 10分以内 |
| メモリ使用量上限 | GitHub Actions標準ランナーの制限内 |

## 排他制御

- 同一ワークフロー・同一refに対する重複実行はキャンセル（concurrency設定）
- Verdaccioはポート4873を使用するため、同一ランナー内での重複起動は不可

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | スクリプト実行開始 |
| 進捗ログ | 処理中 | 各コマンドの実行内容（set -xによるトレース） |
| Verdaccioログ | レジストリ起動中 | 一時ファイルに出力（$tmp_registry_log） |
| 終了ログ | バッチ終了時 | "Exiting without error." |
| エラーログ | エラー発生時 | "ERROR! An error was encountered executing line X" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ実行時間 | 30分 | GitHub Actions（自動タイムアウト） |
| ジョブ失敗 | 失敗時 | プルリクエストステータス |

## 備考

- Verdaccioバージョン: ~6.1.2を使用
- バージョン計算ロジック: プレリリース情報を除去し、パッチ番号を+1する
- アーティファクト保持期間は1日のため、後続のE2Eテストは同一ワークフロー内で実行する必要がある
