# バッチ設計書 9-sanitizer.yml

## 概要

本ドキュメントは、libuvプロジェクトのメモリセーフティテストワークフロー `.github/workflows/sanitizer.yml` の設計仕様を定義する。

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

`sanitizer.yml` は、GitHub Actionsで実行されるメモリセーフティ検証用のCI/CDワークフローである。ASAN（AddressSanitizer）、MSAN（MemorySanitizer）、TSAN（ThreadSanitizer）、UBSAN（UndefinedBehaviorSanitizer）の4種のサニタイザーをLinux、macOS、Windowsの各プラットフォームで実行し、メモリ安全性・スレッド安全性・未定義動作の検出を行う。

**業務上の目的・背景**：libuvはCで記述された非同期I/Oライブラリであり、手動メモリ管理やマルチスレッド処理を多用する。メモリリーク、バッファオーバーフロー、データ競合、未定義動作などの潜在的なバグは通常のテストでは検出困難であり、サニタイザーを使用した専用のテスト実行が必要である。本ワークフローはこれらのメモリ安全性テストを自動化し、品質保証を強化する。

**バッチの実行タイミング**：Pull Request作成/更新時（docs/、隠しファイルを除くパス変更時）、およびバージョンブランチ（v[0-9].*）やmasterブランチへのpush時に自動実行される。

**主要な処理内容**：
1. **sanitizers-linux**: Linux（ubuntu-22.04）上でASAN、MSAN、TSAN、UBSANの4種を実行
   - ASANとMSANはDebugビルド、TSANはReleaseビルド、UBSANはDebugビルド
   - MSANとUBSANはClangコンパイラを指定
   - ASLR無効化（kernel.randomize_va_space=0）
   - TSAN実行時はtsansupp.txt抑制ファイルを使用
2. **sanitizers-macos**: macOS（macos-14）上でASAN、TSAN、UBSANの3種を実行
   - MSANはmacOSではサポートされないため除外
3. **sanitizers-windows**: Windows（windows-2022）上でUBSANを実行
   - LLVM/Clang 17をインストール
   - VS2022同梱Clangのリンク問題を回避

**前後の処理との関連**：CMakeLists.txt（No.4）のサニタイザーオプション（ASAN/MSAN/TSAN/UBSAN）を使用する。CI-unix.yml（No.7）の通常ビルド・テストを補完する。tsansupp.txt（No.20）をTSAN実行時に参照する。

**影響範囲**：メモリ安全性に関するバグ検出に影響する。サニタイザーが検出した問題はPRの品質評価に直接影響する。

## バッチ種別

CI/CDワークフロー（メモリセーフティテスト）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（PR作成/更新、push） |
| 実行時刻 | イベント発生時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | pull_request（パスフィルタ付き）、push（v[0-9].*、master） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actionsランナー | ubuntu-22.04、macos-14、windows-2022 が利用可能であること |
| Clangコンパイラ | MSAN/UBSAN実行にはClangが必要 |
| Ninja ビルドシステム | Linuxジョブではninjaがインストールされること |
| LLVM 17 | Windows UBSANでは外部インストールのLLVM 17が必要 |

### 実行可否判定

パスフィルタにより、docs/配下のみの変更、隠しファイルのみの変更ではワークフローが実行されない（ただし本ワークフロー自身の変更は除く）。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| （ワークフロー入力なし） | - | - | - | トリガーイベントにより自動実行 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| libuvリポジトリ全体 | Git | actions/checkout@v6 でチェックアウト |
| tsansupp.txt | テキスト | ThreadSanitizer抑制設定ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions ログ | テキスト | サニタイザー検出結果を含むテストログ |
| GitHub PR ステータスチェック | ステータス | 各ジョブの成功/失敗ステータス |

### 出力ファイル仕様

該当なし（CI/CDの実行結果はGitHub Actionsのインターフェースで確認）

## 処理フロー

### 処理シーケンス

```
1. sanitizers-linux ジョブ（4環境マトリクス）
   └─ checkout → ninjaインストール → envinfo → ASLR無効化
   └─ CMake構成（各サニタイザーフラグ付き） → ビルド
   └─ TSAN: TSAN_OPTIONS="suppressions=$PWD/tsansupp.txt" で実行
   └─ その他: ./build/uv_run_tests_a で実行
2. sanitizers-macos ジョブ（3環境マトリクス）
   └─ checkout → envinfo
   └─ CMake構成（各サニタイザーフラグ付き） → ビルド
   └─ ./build/uv_run_tests_a で実行
3. sanitizers-windows ジョブ（単一環境）
   └─ checkout → ninjaインストール（choco）→ LLVM 17インストール → envinfo
   └─ CMake構成（UBSAN、Clang）→ ビルド
   └─ ./build-ubsan/uv_run_tests_a で実行
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B[sanitizers-linux x4]
    A --> C[sanitizers-macos x3]
    A --> D[sanitizers-windows x1]
    B --> B1[ASLR無効化] --> B2[CMakeビルド]
    B2 --> B3{TSAN?}
    B3 -->|Yes| B4[suppressions付きテスト]
    B3 -->|No| B5[通常テスト]
    C --> C1[CMakeビルド] --> C2[テスト実行]
    D --> D1[LLVM 17インストール] --> D2[CMake UBSANビルド] --> D3[テスト実行]
```

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

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

該当なし（本ワークフローはCI/CDパイプラインであり、データベースは使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ASAN検出 | バッファオーバーフロー、use-after-free等を検出した場合 | ASANレポートを確認し、メモリ管理コードを修正する |
| - | MSAN検出 | 未初期化メモリの使用を検出した場合 | MSANレポートを確認し、変数初期化を追加する |
| - | TSAN検出 | データ競合を検出した場合 | TSANレポートを確認し、適切な同期処理を追加する |
| - | UBSAN検出 | 未定義動作を検出した場合 | UBSANレポートを確認し、未定義動作を修正する |
| - | ビルドエラー | サニタイザーフラグ付きビルドに失敗した場合 | コンパイラ互換性を確認する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | ワークフローレベルでの自動リトライなし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

サニタイザーが問題を検出した場合、GitHub Actionsのログにスタックトレースを含む詳細レポートが出力される。このレポートを元に原因コードを特定・修正する。TSANの誤検出（false positive）の場合は tsansupp.txt に抑制ルールを追加する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 3ジョブ（Linux 4環境 + macOS 3環境 + Windows 1環境 = 8環境） |
| 目標処理時間 | 各ジョブ数分〜数十分（サニタイザー有効時は通常テストの2〜10倍の実行時間） |
| メモリ使用量上限 | GitHub Actions ランナーのデフォルトリソース（ASANは通常の2〜3倍のメモリを消費） |

## 排他制御

各ジョブは独立したランナーで並列実行される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ビルドログ | ビルド実行時 | CMakeビルド出力 |
| サニタイザーレポート | テスト実行時 | 検出された問題のスタックトレースと詳細情報 |
| 環境情報 | envinfo実行時 | npx envinfo によるランナー環境情報 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ成功/失敗 | 1つでも失敗 | GitHub PRステータスチェック |

## 備考

- Linux環境でASLRを無効化する理由は、新しいカーネルでのPIEスライドの拡大によりASAN/MSANが失敗する問題を回避するため
- TSANはReleaseビルドで実行される（Debug最適化なしではTSANの検出精度が下がるため）
- ASAN/MSAN/UBSANはDebugビルドで実行される（最適化によるスタックフレーム省略を防ぐため）
- MSANはClangでのみサポートされるため、Linux環境でのみ実行される（macOS/Windowsでは除外）
- Windows環境ではVS2022同梱のClangのUBSANランタイムリンク問題があるため、外部インストールのLLVM 17を使用する
- TSAN実行時は tsansupp.txt で既知の無害な競合条件を抑制する
