# バッチ設計書 15-turbo build

## 概要

本ドキュメントは、Tailwind CSSプロジェクトにおけるTurborepoを使用した一括ビルドコマンド「turbo build」のバッチ設計書である。全パッケージの依存関係を解決しながら、playgroundsを除く全ワークスペースパッケージを一括でビルドする。

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

本バッチは、Tailwind CSSモノレポ内の全パッケージをTurborepoの依存関係解決エンジンを使用して効率的に一括ビルドするオーケストレーションコマンドである。`pnpm run build`として実行され、内部的に`turbo build --filter=!./playgrounds/*`が呼び出される。

**業務上の目的・背景**：Tailwind CSSはモノレポ構成で多数のパッケージ（tailwindcss本体、@tailwindcss/cli、@tailwindcss/vite、@tailwindcss/postcss、@tailwindcss/oxide等）を管理している。これらのパッケージ間には依存関係が存在し、ビルド順序を正しく解決する必要がある。Turborepoはこの依存関係をDAG（有向非巡回グラフ）として解析し、並列実行可能なタスクを最大限並列化しつつ、依存関係のあるタスクは適切な順序で逐次実行する。また、ビルド成果物のキャッシュにより、変更のないパッケージのビルドをスキップし、ビルド時間を大幅に短縮する。

**バッチの実行タイミング**：開発者がローカルで`pnpm run build`を実行した時、またはCI/CDワークフロー（Release、Release Insiders、Prepare Release、Integration Tests等）のビルドステップで実行される。

**主要な処理内容**：
1. turbo.jsonの設定に基づく依存関係グラフの構築
2. @tailwindcss/oxide パッケージのビルド（Rust NAPI-RSバイナリ）
3. 各パッケージのbuildタスク実行（依存関係順）
4. ビルド成果物のキャッシュ保存（dist/**ディレクトリ）
5. postbuildスクリプト実行（pack-packages.mjs）

**前後の処理との関連**：本バッチはCI/CDワークフロー内の主要なビルドステップとして使用される。Release（No.11）、Release Insiders（No.12）、Prepare Release（No.13）、Integration Tests（No.14）の各ワークフローが本バッチを呼び出す。ビルド後にはpostbuildスクリプト（pack-packages.mjs / No.1）が自動実行される。turbo dev（No.16）は本バッチの開発モード版である。

**影響範囲**：全ワークスペースパッケージ（playgroundsを除く）のdist/ディレクトリ。@tailwindcss/oxideのネイティブバイナリ（.node、.wasm等）。Turborepoのローカルキャッシュ。

## バッチ種別

ビルドオーケストレーション

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動/CI） |
| 実行時刻 | 不定 |
| 実行曜日 | 不定 |
| 実行日 | 不定 |
| トリガー | 手動（pnpm run build） / CI/CDワークフローのステップ |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| pnpmがインストール済み | パッケージマネージャとしてpnpm v9.6.0以上が必要 |
| Node.jsが利用可能 | Node.js v24推奨 |
| Rustツールチェーンがインストール済み | @tailwindcss/oxideのビルドにRustが必要 |
| 依存関係がインストール済み | pnpm installが完了していること |
| turboがインストール済み | devDependenciesとしてturbo v2.7.6以上がインストール済み |

### 実行可否判定

前提条件がすべて満たされている場合に実行可能。Turborepoは内部的にキャッシュの有効性を判定し、変更のないパッケージのビルドをスキップする。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| FEATURES_ENV | string | No | なし | 有効化する機能セット（stableが指定された場合、安定版機能のみが有効） |
| RUSTUP_HOME | string | No | ~/.rustup | Rustupのホームディレクトリ（globalPassThroughEnvで透過） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| turbo.json | JSONC | Turborepoのタスク定義・依存関係・キャッシュ設定 |
| package.json（ルート） | JSON | buildスクリプト定義（turbo build --filter=!./playgrounds/*） |
| package.json（各パッケージ） | JSON | 各パッケージのbuildスクリプト定義 |
| pnpm-workspace.yaml | YAML | ワークスペースパッケージの定義 |
| 各パッケージのソースコード | TypeScript/Rust/CSS | ビルド対象のソースコード |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/*/dist/ | JavaScript/TypeScript定義/CSS | 各パッケージのビルド成果物 |
| crates/node/*.node | バイナリ | @tailwindcss/oxideのネイティブバイナリ |
| crates/node/*.wasm | バイナリ | @tailwindcss/oxideのWASMバイナリ |
| crates/node/index.js, index.d.ts | JavaScript/TypeScript | @tailwindcss/oxideのJSバインディング |
| dist/*.tgz | tarball | postbuildで生成されるパッケージアーカイブ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | dist/**（各パッケージ内） |
| 出力先 | 各パッケージディレクトリ内のdist/ |
| 文字コード | UTF-8（JavaScript/TypeScript）/ バイナリ（.node/.wasm） |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. turbo buildコマンド開始
   └─ --filter=!./playgrounds/* でplaygroundsパッケージを除外
2. 依存関係グラフの構築
   └─ turbo.jsonの設定に基づきタスク間の依存関係を解析
3. @tailwindcss/oxide ビルド（最初に実行、他パッケージの前提）
   ├─ Rustソースコードのコンパイル（crates/oxide, crates/node）
   ├─ NAPI-RSによるNode.jsバインディング生成
   ├─ 出力: index.d.ts, index.js, *.node
   └─ inputs: src/**, build.rs, Cargo.toml等から変更検知
4. 依存パッケージのビルド（依存関係順に並列実行）
   ├─ tailwindcss本体のビルド
   ├─ @tailwindcss/cli のビルド
   ├─ @tailwindcss/vite のビルド
   ├─ @tailwindcss/postcss のビルド
   ├─ @tailwindcss/browser のビルド
   ├─ @tailwindcss/upgrade のビルド
   └─ その他パッケージのビルド
5. 各パッケージの出力をdist/**に保存
6. Turborepoキャッシュの更新
7. postbuildスクリプト実行（pack-packages.mjs）
   └─ 全パッケージのtgzアーカイブをdist/に生成
```

### フローチャート

```mermaid
flowchart TD
    A[pnpm run build] --> B[turbo build --filter=!./playgrounds/*]
    B --> C[依存関係グラフ構築]
    C --> D{キャッシュヒット?}
    D -->|全パッケージヒット| E[キャッシュから復元]
    D -->|一部/全ミス| F[@tailwindcss/oxide ビルド]
    F --> G[依存パッケージの並列ビルド]
    G --> H[ビルド成果物をdist/**に出力]
    H --> I[Turborepoキャッシュ更新]
    E --> J[postbuild: pack-packages.mjs]
    I --> J
    J --> K[ビルド完了]
```

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

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

本バッチはデータベースを使用しない。

| 処理 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

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

N/A（データベース操作なし）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| RUST_BUILD_FAIL | Rustビルドエラー | @tailwindcss/oxideのRustコンパイルエラー | Rustソースコードを修正、Cargoの依存関係を確認 |
| TS_BUILD_FAIL | TypeScriptビルドエラー | TypeScriptコンパイルエラー | TypeScriptソースコードを修正 |
| DEP_MISSING | 依存関係エラー | pnpm installが未実行 | pnpm installを実行 |
| CACHE_CORRUPT | キャッシュ破損 | Turborepoキャッシュの破損 | turbo build --force でキャッシュを無視して再ビルド |
| POSTBUILD_FAIL | postbuildエラー | pack-packages.mjs実行エラー | スクリプトのエラーログを確認 |

### リトライ仕様

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

### 障害時対応

1. Rustビルド失敗時：Cargoのエラーメッセージを確認し、Rustソースコードまたは依存関係を修正する。
2. TypeScriptビルド失敗時：TypeScriptのコンパイルエラーを確認し、ソースコードを修正する。
3. キャッシュ関連の問題：`turbo build --force`を使用してキャッシュを無視した再ビルドを試みる。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | パッケージ単位 |
| コミットタイミング | 各パッケージのビルド完了時にキャッシュ保存 |
| ロールバック条件 | ビルド失敗時は成果物が生成されない（部分的な成果物は残る可能性あり） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ワークスペース内の全パッケージ（playgrounds除外） |
| 目標処理時間 | キャッシュヒット時: 数秒 / フルビルド: CI環境で15分以内 |
| メモリ使用量上限 | Rustコンパイル時に数GB使用の可能性あり |

## 排他制御

Turborepoが内部的にタスクの並列実行と排他制御を管理する。同一パッケージのビルドタスクが同時に実行されることはない。`dependsOn: ["^build"]`設定により、依存先パッケージのビルドが完了するまで依存元パッケージのビルドは開始されない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | turboコマンド実行時 | Turborepo TUI（ui: "tui"）による進捗表示 |
| 進捗ログ | 各パッケージビルド中 | パッケージ名、ビルドステータス、キャッシュヒット/ミス |
| 終了ログ | turboコマンド完了時 | 総ビルド時間、キャッシュヒット率 |
| エラーログ | ビルド失敗時 | 失敗したパッケージ名とエラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド時間 | CI環境で15分（timeout-minutes） | CI/CDワークフローのタイムアウト設定 |
| ビルドエラー | 1件 | ターミナル出力 / CI/CDワークフローのステータス |

## 備考

- turbo.jsonでは以下のタスク定義がある：
  - `build`: 汎用ビルドタスク。`dependsOn: ["^build"]`で依存パッケージのビルドを先行実行。出力は`dist/**`。環境変数`FEATURES_ENV`を監視。
  - `@tailwindcss/oxide#build`: Oxide専用ビルドタスク。出力は`index.d.ts`、`index.js`、`*.node`。入力は`src/**/*`、`build.rs`、`Cargo.toml`等のRust関連ファイル。
- `globalPassThroughEnv: ["RUSTUP_HOME"]`により、Rustupが標準以外のディレクトリにインストールされている場合もパスが透過される。
- UIモードは`tui`（Terminal User Interface）が設定されており、ターミナルでのリッチな進捗表示が有効。
- package.jsonの`build`スクリプトは`turbo build --filter=!./playgrounds/*`であり、playgroundsパッケージがビルド対象から除外される。
- postbuildスクリプト（`node ./scripts/pack-packages.mjs`）はpackage.jsonのscripts.postbuildとして定義されており、`pnpm run build`完了後に自動実行される。
- ワークスペースパッケージ: crates/node、crates/node/npm/*、packages/*、playgrounds/*、integrations
