# バッチ設計書 2-cake

## 概要

本ドキュメントは、CoffeeScriptプロジェクトのビルドツール `cake` コマンドの設計仕様を記述したものです。MakeやRakeに類似したタスクランナーとして機能します。

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

`cake` コマンドは、CoffeeScriptプロジェクトにおけるビルドタスクを管理・実行するためのタスクランナーです。プロジェクトルートに配置された `Cakefile` に定義されたタスクを実行し、ビルド、テスト、ドキュメント生成などの自動化を支援します。

**業務上の目的・背景**：CoffeeScriptプロジェクトでは、ソースコードのコンパイル、テスト実行、ドキュメント生成など、繰り返し行われるタスクが多数存在します。`cake` はこれらのタスクを `Cakefile` に定義し、一貫した方法で実行できるようにするツールです。GNU MakeのMakefile、RubyのRakefile、Node.jsのGruntfile/Gulpfileに相当する役割を果たし、プロジェクトの開発効率を向上させます。

**バッチの実行タイミング**：随時（手動実行）。開発者がビルド、テスト、リリースなどのタスクを実行したいときに任意のタイミングで実行されます。CI/CDパイプラインからも呼び出されることがあります。

**主要な処理内容**：
1. カレントディレクトリまたは親ディレクトリから `Cakefile` を検索
2. `Cakefile` をCoffeeScriptとしてコンパイル・実行
3. コマンドライン引数のパース（タスク名とオプション）
4. グローバルに登録された `task()` 関数でタスクを定義
5. 指定されたタスクの `action` 関数を実行
6. タスクが指定されない場合は利用可能なタスク一覧を表示

**前後の処理との関連**：`cake` は `coffee` コマンドをビルドやテストで内部的に使用します。npm scriptsから呼び出されることも多く（例：`npm test` は `cake test` を実行）、CI/CDパイプラインの一部として組み込まれます。

**影響範囲**：プロジェクトのソースファイル、生成物（lib/配下のJSファイル、docs配下のドキュメント等）、テスト結果に影響を与えます。

## バッチ種別

CLIツール / タスクランナー

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | なし（手動実行） |
| 実行曜日 | なし |
| 実行日 | なし |
| トリガー | 手動 / npm script / CI/CD |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js 6以上 | ES6構文（分割代入等）をサポートするNode.jsランタイムが必要 |
| CoffeeScriptモジュール | lib/coffeescript配下のコンパイラモジュールが存在すること |
| Cakefile | カレントディレクトリまたは親ディレクトリにCakefileが存在すること |

### 実行可否判定

1. Node.jsランタイムのバージョンチェック（ES6構文のサポート確認）
2. CoffeeScriptモジュールの存在確認
3. Cakefileの存在確認（ディレクトリを遡って検索）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| taskName | string | No | なし | 実行するタスク名（複数指定可） |
| Cakefileで定義されたオプション | 可変 | No | なし | option()で定義されたカスタムオプション |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Cakefile | CoffeeScript | タスク定義ファイル |
| コマンドライン引数 | テキスト | タスク名とオプション |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | タスク実行結果、タスク一覧 |
| 標準エラー | テキスト | エラーメッセージ |
| 各種ファイル | タスク依存 | タスクが生成するファイル |

### 出力ファイル仕様

タスクの内容に依存します。詳細は各タスク（build、test等）の設計書を参照してください。

## 処理フロー

### 処理シーケンス

```
1. エントリポイント（bin/cake）
   └─ Node.jsランタイムのES6サポートを確認
2. CoffeeScriptモジュールの検索とロード
   └─ node_modules/coffeescript/lib/coffeescriptまたはローカルlibディレクトリを検索
3. cake.run()の実行
   └─ cakefileDirectory()でCakefileを検索
4. Cakefileのコンパイルと実行
   └─ CoffeeScript.run()でCakefileをevalし、task()でタスクを登録
5. 引数解析
   └─ optparse.OptionParserで引数をパース
6. タスク実行または一覧表示
   └─ タスク指定あり：invoke()でタスクを実行
   └─ タスク指定なし：printTasks()でタスク一覧を表示
```

### フローチャート

```mermaid
flowchart TD
    A[bin/cake実行] --> B{ES6サポート確認}
    B -->|失敗| C[エラー出力して終了]
    B -->|成功| D[CoffeeScriptモジュール検索]
    D --> E[cake.run呼び出し]
    E --> F[Cakefile検索]
    F --> G{Cakefile存在?}
    G -->|No| H[エラー: Cakefile not found]
    G -->|Yes| I[Cakefileコンパイル・実行]
    I --> J[タスク登録]
    J --> K[引数パース]
    K --> L{タスク指定あり?}
    L -->|No| M[タスク一覧表示]
    L -->|Yes| N[invoke: タスク実行]
    N --> O{タスク存在?}
    O -->|No| P[エラー: No such task]
    O -->|Yes| Q[タスクaction実行]
```

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

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

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | ランタイムエラー | Node.js 6未満で実行 | Node.js 6以上をインストール |
| 1 | ファイルエラー | Cakefileが見つからない | プロジェクトルートにCakefileを作成 |
| 1 | タスクエラー | 指定されたタスクが存在しない | cake（引数なし）でタスク一覧を確認 |
| 1 | パースエラー | オプション解析失敗 | オプション構文を確認 |

### リトライ仕様

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

### 障害時対応

- Cakefileが見つからない場合：エラーメッセージを表示して終了
- タスクが見つからない場合：エラーメッセージとタスク一覧表示方法を案内
- オプションパースエラー：エラーメッセージを表示して終了

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（タスク実行は各タスクの実装に依存） |
| コミットタイミング | なし |
| ロールバック条件 | なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回の実行で1〜数個のタスク |
| 目標処理時間 | タスク内容に依存 |
| メモリ使用量上限 | Node.jsデフォルト制限に従う |

## 排他制御

- 同時実行可能（ただしタスクの内容によっては競合の可能性あり）
- タスク間の依存関係は `invoke()` で明示的に制御

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| タスク一覧ログ | 引数なし実行時 | Cakefileのパスと定義されたタスク一覧 |
| エラーログ | エラー発生時 | エラーメッセージとヘルプ情報 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| なし | なし | なし |

## 備考

- `cake` はGNU MakeやRuby Rakeに着想を得たタスクランナーです
- Cakefile内では `task()`, `option()`, `invoke()` 関数がグローバルに利用可能です
- タスクは非同期実行されるため、実行順序が期待と異なる場合があります
- `__originalDirname` グローバル変数で元のディレクトリパスを参照できます
- CoffeeScript.register()により、require()で.coffeeファイルを直接読み込み可能になります
