# バッチ設計書 1-Node CI - ビルド・ユニットテスト

## 概要

本ドキュメントは、Decap CMSプロジェクトにおけるNode CI（ビルド・ユニットテスト）ワークフローのバッチ設計書である。GitHub Actionsで定義されたCI/CDパイプラインのうち、lint・型チェック・ユニットテストを複数OS・Node.jsバージョンのマトリクスで実行するジョブについて記述する。

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

本バッチは、Decap CMSのソースコードに対する品質検証を自動的に実行するCI/CDバッチである。コードの変更がmain/masterブランチへのpushまたはPull Request時に自動トリガーされ、複数の環境でlint・型チェック・ユニットテストを実行することで、コードの品質と互換性を担保する。

**業務上の目的・背景**：Decap CMSはオープンソースのCMSプロジェクトであり、多数の開発者が並行してコードを変更する。コード変更がメインブランチに統合される前に、自動的にlint（コード規約チェック）、TypeScript型チェック、ユニットテストを実行することで、回帰バグやコード規約違反を早期に検出し、コードベースの品質を維持する必要がある。複数のOS（Ubuntu・macOS・Windows）およびNode.jsバージョン（22.x・24.x）での検証により、クロスプラットフォーム互換性も確保する。

**バッチの実行タイミング**：main/masterブランチへのpush時、およびPull Requestのオープン・同期・再オープン時にイベント駆動で自動実行される。

**主要な処理内容**：
1. dorny/paths-filterによる変更ファイルのフィルタリング（website以外の変更を検出）
2. マトリクス戦略に基づく複数環境でのジョブ起動（Ubuntu/macOS/Windows x Node.js 22.x/24.x）
3. リポジトリのチェックアウトとNode.jsセットアップ
4. npm ciによる依存関係のインストール（Cypressバイナリはスキップ）
5. npm run test:ci の実行（lint-quiet、type-check、test:unitの順次実行）

**前後の処理との関連**：同一ワークフロー内のchangesジョブ（パスフィルタ）の結果に依存する。E2Eテストジョブ（No.2）とは並列で実行される。本バッチの成功がPRマージの前提条件となる。

**影響範囲**：本バッチはリポジトリ内の全パッケージ（packages/配下）のソースコードに対してlint・型チェック・テストを実行する。テスト結果はGitHub上のステータスチェックとして報告され、PRのマージ可否に影響する。

## バッチ種別

CI/CD（継続的インテグレーション - ビルド検証・品質チェック）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | 該当なし（イベント発生時） |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | main/masterブランチへのpush、Pull Requestのopened/synchronize/reopened |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHubリポジトリへのアクセス | actions/checkout@v4でリポジトリをチェックアウト可能であること |
| Node.jsランタイム | actions/setup-node@v4でNode.js 22.xまたは24.xがセットアップ可能であること |
| npm依存関係 | npm ciが正常に完了すること（package-lock.jsonが最新であること） |
| 変更ファイルの存在 | dorny/paths-filterでwebsite以外のファイルに変更が検出されること |

### 実行可否判定

changesジョブのdorny/paths-filterステップで、website/ディレクトリ以外のファイルに変更があるかを判定する。`needs.changes.outputs.cms == 'true'`の場合のみbuild-unitジョブが実行される。website配下のみの変更の場合はスキップされる。また、concurrencyグループ`ci-${{ github.workflow }}-${{ github.ref }}`により、同一ブランチでの重複実行はキャンセルされる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| CYPRESS_INSTALL_BINARY | 環境変数 | No | 0 | Cypressバイナリのインストールをスキップするためのフラグ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHubリポジトリ（ソースコード） | Git | チェックアウト対象のソースコード一式 |
| package-lock.json | JSON | npm ciで使用される依存関係ロックファイル |
| .eslintrc / eslint設定 | JSON/JS | ESLint実行時の設定ファイル |
| tsconfig.json | JSON | TypeScript型チェック用の設定ファイル |
| jest.config.js | JS | Jestユニットテスト用の設定ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHubステータスチェック | GitHub API | ジョブの成功/失敗ステータスがPRに報告される |
| GitHub Actionsログ | テキスト | lint・型チェック・テストの実行ログ |

### 出力ファイル仕様

本バッチではファイル出力は行わない。実行結果はGitHub Actionsのジョブステータスおよびログとして記録される。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし |
| 出力先 | GitHub Actionsログ |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. changesジョブ（パスフィルタリング）
   └─ dorny/paths-filter@v2でwebsite以外の変更を検出
2. build-unitジョブ開始（changesジョブの結果がtrueの場合）
   └─ マトリクス戦略で複数環境を並列起動
       - ubuntu-latest + Node.js 24.x
       - ubuntu-latest + Node.js 22.x
       - macos-latest + Node.js 24.x
       - windows-latest + Node.js 24.x
3. リポジトリチェックアウト
   └─ actions/checkout@v4
4. Node.jsセットアップ
   └─ actions/setup-node@v4でマトリクスのNode.jsバージョンをセットアップ（npmキャッシュ有効）
5. バージョン情報ログ出力
   └─ node --version && npm --version
6. 依存関係インストール
   └─ npm ci（CYPRESS_INSTALL_BINARY=0でCypressバイナリをスキップ）
7. テスト実行
   └─ npm run test:ci
       ├─ lint-quiet（stylelint + eslint を--quietモードで並列実行）
       ├─ type-check（tsc --noEmit）
       └─ test:unit（cross-env NODE_ENV=test jest --no-cache）
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロートリガー: push/PR] --> B[changesジョブ: パスフィルタ]
    B --> C{website以外の変更あり?}
    C -->|なし| D[スキップ]
    C -->|あり| E[build-unitジョブ開始]
    E --> F[マトリクス環境セットアップ]
    F --> G[リポジトリチェックアウト]
    G --> H[Node.jsセットアップ]
    H --> I[バージョン情報ログ出力]
    I --> J[npm ci: 依存関係インストール]
    J --> K[npm run test:ci]
    K --> L[lint-quiet: CSS/JSリント]
    L --> M[type-check: TypeScript型チェック]
    M --> N[test:unit: Jestユニットテスト]
    N --> O{全テスト成功?}
    O -->|成功| P[ジョブ成功]
    O -->|失敗| Q[ジョブ失敗]
    D --> R[ワークフロー終了]
    P --> R
    Q --> R
```

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

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | 該当なし |

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 依存関係インストール失敗 | npm ciがpackage-lock.jsonとpackage.jsonの不整合を検出した場合 | package-lock.jsonを再生成してコミットする |
| - | lintエラー | ESLint/Stylelintの規約違反が検出された場合 | エラー箇所を修正するか、必要に応じてルールを調整する |
| - | 型チェックエラー | TypeScriptの型エラーが検出された場合 | 型定義を修正する |
| - | テスト失敗 | Jestユニットテストがfailした場合 | テストコードまたはソースコードを修正する |
| - | 環境セットアップ失敗 | Node.jsバージョンのインストールに失敗した場合 | GitHub Actionsのランナーキャッシュを確認し、再実行する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 自動リトライなし（GitHub Actions UIから手動で再実行可能） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

バッチ（ワークフロー）失敗時は以下の手順で対応する：
1. GitHub Actionsのログでどのステップでエラーが発生したかを確認する
2. lintエラー・型チェックエラー・テスト失敗の場合はソースコードを修正して再pushする
3. 環境起因のエラー（ネットワーク障害等）の場合はGitHub Actions UIから「Re-run failed jobs」で再実行する
4. fail-fast: trueが設定されているため、1つのマトリクスジョブが失敗すると他のジョブもキャンセルされる

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 全パッケージ（約30パッケージ）のlint・型チェック・テスト |
| 目標処理時間 | 明示的な上限なし（通常10-20分程度） |
| メモリ使用量上限 | 明示的な上限なし（GitHub Actionsランナーのデフォルトメモリ） |

## 排他制御

concurrencyグループ`ci-${{ github.workflow }}-${{ github.ref }}`により、同一ブランチで同一ワークフローの重複実行が防止される。`cancel-in-progress: true`が設定されているため、新しい実行がトリガーされると進行中の古い実行はキャンセルされる。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ジョブ開始時 | GitHub Actionsにより自動的にジョブ開始が記録される |
| バージョンログ | Node.jsセットアップ後 | `node --version && npm --version`の出力 |
| lint結果ログ | lint実行後 | stylelint・eslintの実行結果（--quietモードで警告は非表示） |
| 型チェック結果ログ | type-check実行後 | tsc --noEmitの実行結果 |
| テスト結果ログ | test:unit実行後 | Jest実行結果（テストスイート数・テスト件数・成功/失敗） |
| 終了ログ | ジョブ終了時 | GitHub Actionsにより自動的にジョブ完了ステータスが記録される |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ成功/失敗 | 失敗時 | GitHub PRステータスチェック、PRレビュアーへの通知 |
| ワークフロー実行時間 | 明示的な閾値なし | GitHub Actions UI |

## 備考

- マトリクス戦略のfail-fastがtrueのため、1つの環境で失敗すると他の環境のジョブもキャンセルされる
- Cypressバイナリのインストールはスキップされる（E2Eテストは別ジョブで実行）
- npmキャッシュが有効化されており、依存関係のインストール時間が短縮される
- 本ワークフローはNo.2（E2Eテスト）と同一のnodejs.ymlファイル内で定義されている
