# バッチ設計書 6-lock-pre-release-versions.mjs

## 概要

本ドキュメントは、Tailwind CSSプロジェクトにおけるビルドスクリプト `lock-pre-release-versions.mjs` のバッチ設計書である。プレリリースバージョンのパッケージ間依存を `workspace:*` に統一する処理の仕様を定義する。

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

本バッチは、プレリリースバージョン（バージョン番号に `-` を含むもの）のパッケージにおいて、ワークスペース内の依存関係を `workspace:*` に統一する処理を行う。

**業務上の目的・背景**：pnpmモノレポでは、ワークスペース間の依存関係は `workspace:^` や `workspace:~` のように記述できる。しかし、プレリリースバージョン（例：`0.0.0-development.0`, `0.0.0-insiders.{hash}`）では、これらの指定がnpm公開時に適切に解決されない場合がある。本バッチにより、プレリリース時のワークスペース依存を全て `workspace:*` に統一し、pnpmが公開時に正しいバージョンに解決できるようにする。

**バッチの実行タイミング**：リリースワークフローでnpm公開前に実行される。

**主要な処理内容**：
1. pnpmコマンドで全ワークスペースパッケージ（playgroundsを除く）のパスを取得する
2. 各パッケージの `package.json` を読み込み、バージョンに `-` を含むプレリリースパッケージを対象とする
3. `dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies` の各セクションを走査する
4. `workspace:` プレフィックスを持ち、かつ `workspace:*` でない依存を `workspace:*` に変更する
5. 変更がある場合、prettierでフォーマットしてpackage.jsonを保存する

**前後の処理との関連**：リリースワークフローでビルド完了後、npm公開前に実行される。`pre-publish-optimizations.mjs` と同時期に実行される前処理の一つ。

**影響範囲**：プレリリースバージョンのパッケージの `package.json` が変更される。具体的には、ワークスペース依存のバージョン指定が `workspace:*` に統一される。

## バッチ種別

データ更新 / 依存関係正規化

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース時） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | リリースワークフローからの呼び出し |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| pnpmがインストール済み | pnpmコマンドが実行可能であること |
| prettierがインストール済み | package.jsonのフォーマットに使用 |
| プレリリースバージョン | パッケージのバージョンに `-` が含まれていること |
| Node.js実行環境 | ESModule対応のNode.jsバージョンがインストールされていること |

### 実行可否判定

全パッケージを走査するが、バージョンに `-` を含まないパッケージはスキップされる。また、ワークスペース依存が既に `workspace:*` であるか、`workspace:` プレフィックスを持たない依存もスキップされる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | コマンドライン引数は受け取らない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| 各パッケージの package.json | JSON | バージョン情報と依存関係の取得・更新に使用 |
| pnpm ワークスペース情報 | CLI出力 | `pnpm -r exec pwd` によるワークスペースパス一覧の取得 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 各パッケージの package.json | JSON | ワークスペース依存が `workspace:*` に統一されたファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | package.json（既存ファイルの上書き） |
| 出力先 | 各ワークスペースパッケージのディレクトリ |
| 文字コード | UTF-8 |
| フォーマット | Prettierによる整形済みJSON |

## 処理フロー

### 処理シーケンス

```
1. ワークスペースパス取得
   └─ pnpm --silent --filter=!./playgrounds/* -r exec pwd で全ワークスペースのパスを取得
2. パッケージ走査
   └─ 各パッケージの package.json を読み込む
3. プレリリース判定
   └─ バージョンに '-' が含まれるか確認（含まれない場合はスキップ）
4. 依存関係走査
   └─ dependencies, devDependencies, peerDependencies, optionalDependencies の各セクションを走査
5. ワークスペース依存の正規化
   └─ workspace:プレフィックスの依存を workspace:* に変更
6. ファイル保存
   └─ 変更がある場合、prettierでフォーマットしてpackage.jsonを保存
7. 完了通知
   └─ "Done." をコンソールに出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[pnpmでワークスペースパス取得]
    B --> C[各パッケージのpackage.json読み込み]
    C --> D{プレリリースバージョン?}
    D -->|いいえ| E[スキップ]
    D -->|はい| F[依存関係セクションを走査]
    F --> G{workspace:依存あり かつ workspace:*でない?}
    G -->|はい| H[workspace:*に変更]
    G -->|いいえ| I[変更なし]
    H --> J{変更あり?}
    I --> J
    J -->|はい| K[prettierでフォーマットして保存]
    J -->|いいえ| L[次のパッケージへ]
    K --> L
    E --> L
    L --> C
    C --> M[Done. 出力]
    M --> N[バッチ終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | pnpm exec 失敗 | ワークスペース構成が不正な場合 | エラーをconsole.errorに出力し、process.exit(1)で終了 |
| - | ファイル読み書き失敗 | package.jsonが読めない/書けない場合 | ファイルパーミッションを確認 |

### リトライ仕様

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

### 障害時対応

バッチ失敗時は、gitでpackage.jsonの変更を元に戻し、原因を特定した上で再実行する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（ファイルシステム操作のため） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A（gitによるロールバックが可能） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ワークスペース内の全パッケージ数 |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 特に定めなし |

## 排他制御

リリースワークフロー内で順次実行されるため、同時実行の考慮は不要。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| エラーログ | pnpm exec 失敗時 | エラーオブジェクト |
| 終了ログ | 処理完了時 | "Done." |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 特に定めなし | - | - |

## 備考

- プレリリースバージョンの判定はバージョン文字列に `-` が含まれるかどうかで行われる（例：`0.0.0-development.0`, `0.0.0-insiders.{hash}`）
- `workspace:*` は既にその値である場合と、`workspace:` プレフィックスを持たない場合はスキップされる
- 対象となる依存関係のセクションは4種類：`dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`
- prettierのフォーマットは各package.jsonのパスに基づいた設定が使用される
- `shouldUpdate` フラグにより、変更がない場合はファイル書き込みをスキップする最適化が行われている
