# バッチ設計書 18-koch.nim（runCI）

## 概要

本ドキュメントは、Nimコンパイラの継続的インテグレーション（CI）を実行する `koch runCI` コマンドの設計書です。このコマンドはGitHub ActionsなどのCI環境で使用され、ブートストラップ、テスト、パッケージビルドを含む完全なCI実行を行います。

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

このバッチは、NimコンパイラプロジェクトのCI/CDパイプラインで使用される包括的なテスト・検証プロセスを実行します。コンパイラのブートストラップから、各種テストスイートの実行、ドキュメント生成テスト、パッケージビルドまでを自動化し、コードの品質を継続的に監視します。

**業務上の目的・背景**：ソフトウェア開発において、変更がプロジェクト全体に悪影響を及ぼさないことを継続的に検証することが重要です。Nimコンパイラは複雑なプロジェクトであり、言語機能、標準ライブラリ、ツール群、ドキュメント生成など多岐にわたる機能を持ちます。runCIは、これらすべての領域をカバーする包括的なテストを自動実行し、リグレッションの早期発見と品質維持を実現します。

**バッチの実行タイミング**：以下のタイミングで実行されます：
- GitHub ActionsなどのCI環境でのPR検証時
- マージ前の最終確認時
- 定期的なナイトリービルド時
- リリース前の品質確認時

**主要な処理内容**：
1. ホスト情報の出力（OS、CPU、環境情報）
2. Nimコンパイラのブートストラップ（-d:release -d:nimStrictMode）
3. nimbleのビルド
4. smtpパッケージのインストール
5. テストツールのビルド（testTools）
6. 外部パッケージのインストール（zip、opengl、sdl1、jester）
7. nimscriptテストの実行
8. testamentによる全テストスイートの実行
9. libffiサポート付きビルドとテスト（POSIXのみ）
10. nimdoc、rst2html、nimprettyのテスト実行
11. nimsuggestのテスト実行（POSIXのみ）
12. refcメモリ管理でのブートストラップテスト

**前後の処理との関連**：CI環境で独立して実行されるため、前提となるバッチはありません。ただし、Nimソースコードがチェックアウトされている必要があります。

**影響範囲**：CI環境全体に影響し、テスト結果がGitHub ActionsなどのCIシステムに報告されます。

## バッチ種別

CI/CD / 継続的インテグレーション

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | PR作成時、マージ時、定期ビルド |
| 実行時刻 | トリガーに依存 |
| 実行曜日 | 任意 |
| 実行日 | 任意 |
| トリガー | CI/CDパイプライン（GitHub Actions等） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| CI環境 | GitHub Actions、Azure Pipelines等の実行環境 |
| Nimソースコードがチェックアウト済み | リポジトリがクローンされていること |
| Cコンパイラが利用可能 | GCC、Clang等がインストールされていること |
| ネットワーク接続 | 外部パッケージのダウンロードに必要 |

### 実行可否判定

引数が指定された場合はエラーになります（`doAssert cmd.len == 0`）。CI環境で必要な環境が整っていない場合、各ステップでエラーが発生します。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | runCIは引数を受け付けない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| compiler/nim.nim | Nimソースファイル | コンパイラソース |
| tests/ | ディレクトリ | テストスイート |
| nimdoc/ | ディレクトリ | ドキュメントテスト |
| nimsuggest/ | ディレクトリ | nimsuggestテスト |
| nimpretty/ | ディレクトリ | nimprettyテスト |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | テスト結果、進捗情報 |
| bin/ | ディレクトリ | ビルドされた実行ファイル |
| CI終了コード | 整数 | 0=成功、非0=失敗 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 各種ビルド成果物 |
| 出力先 | bin/、build/ |
| 文字コード | バイナリ |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. ホスト情報出力
   └─ hostInfo()でOS、CPU、int/floatサイズ、エンディアン、cwdを出力
2. Nimブートストラップ
   └─ kochExecFold("boot -d:release -d:nimStrictMode --lib:lib")
3. nimbleビルド
   └─ kochExecFold("nimble")
4. smtpインストール
   └─ execFold("nimble install smtp -y")
5. パッケージテストモード分岐
   └─ NIM_TEST_PACKAGES=1の場合：パッケージテストのみ実行
   └─ それ以外：通常のCIフロー
6. テストツールビルド（通常モード）
   └─ testTools()でnimgrep、nimpretty、testamentをビルド
7. 外部パッケージインストール
   └─ zip、opengl、sdl1、jester@#headをインストール
8. nimscriptテスト実行
   └─ execFold("nim e tests/test_nimscript.nims")
9. Windowsコンパイルテスト（Windowsのみ）
   └─ genode OS向けクロスコンパイルテスト
10. testamentによるテスト実行
    └─ execFold("nim c -r ... testament ... all -d:nimCoroutines")
11. libffiテスト（POSIXのみ）
    └─ libffiインストール、FFI対応ビルド、テスト実行
12. ドキュメントテスト
    └─ nimdoc/tester、nimdoc/rsttester実行
13. nimprettyテスト
    └─ nimpretty/tester.nim実行
14. nimsuggestテスト（POSIXのみ）
    └─ nimsuggest_testingビルド、nimsuggest/tester実行
15. refcブートストラップテスト
    └─ boot -d:release --mm:refc -d:nimStrictMode --lib:lib
```

### フローチャート

```mermaid
flowchart TD
    A[runCI開始] --> B[ホスト情報出力]
    B --> C[Nimブートストラップ]
    C --> D[nimbleビルド]
    D --> E[smtpインストール]
    E --> F{NIM_TEST_PACKAGES?}
    F -->|Yes| G[パッケージテスト実行]
    G --> Z[runCI完了]
    F -->|No| H[testToolsビルド]
    H --> I[外部パッケージインストール]
    I --> J[nimscriptテスト]
    J --> K{Windows?}
    K -->|Yes| L[genodeコンパイルテスト]
    L --> M
    K -->|No| M[testamentテスト実行]
    M --> N{POSIX?}
    N -->|Yes| O[libffiテスト]
    O --> P
    N -->|No| P[ドキュメントテスト]
    P --> Q[nimprettyテスト]
    Q --> R{POSIX?}
    R -->|Yes| S[nimsuggestテスト]
    S --> T
    R -->|No| T[refcブートストラップテスト]
    T --> Z
```

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

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

このバッチはデータベース操作を行いません。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | N/A |

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| assertionエラー | 引数エラー | 引数が指定された | 引数なしで実行 |
| コンパイルエラー | ソースエラー | ブートストラップ失敗 | ソースコードを確認 |
| テスト失敗 | テストエラー | テストスイート失敗 | 失敗したテストを確認 |
| ネットワークエラー | 接続失敗 | パッケージインストール失敗 | ネットワーク接続を確認 |

### リトライ仕様

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

### 障害時対応

1. 失敗したステップのログを確認
2. ローカル環境で同じテストを再現して調査
3. 必要に応じてソースコードを修正してPRを更新

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回のCI実行 |
| 目標処理時間 | 30分〜1時間程度（環境依存） |
| メモリ使用量上限 | CI環境の制限に依存 |

## 排他制御

CI環境は通常、ジョブごとに独立した環境で実行されるため、排他制御は不要です。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ホスト情報 | CI開始時 | hostOS、hostCPU、int/floatサイズ等 |
| フォールドログ | 各ステップ | "runCI: <コマンド>"、各ステップの出力 |
| テスト結果 | テスト完了時 | 成功/失敗件数、失敗したテストの詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| CI結果 | 非ゼロ終了コード | GitHub PR、Slackなど（CI設定依存） |
| テスト失敗 | 1件以上 | CI/CDシステム |

## 備考

- `NIM_TEST_PACKAGES=1`環境変数でパッケージテストモードに切り替え可能
- `NIM_TESTAMENT_BATCH`環境変数でテストのバッチ分割が可能
- `NIM_TESTAMENT_REMOTE_NETWORKING=1`を設定してリモートネットワーキングテストを有効化
- `-d:nimStrictMode`はコンパイラの厳格モードを有効にし、警告をエラーとして扱います
- `--lib:lib`はOpenBSD等での互換性のために必要なオプションです
- refcモードでのブートストラップテストは、古いメモリ管理方式との互換性を確認します
- POSIXのみのテスト（libffi、nimsuggest）はWindows環境ではスキップされます
- inFold/execFoldはCI環境でログをグループ化するためのユーティリティです
