# 非機能要件定義書

## 概要

本ドキュメントは、CoffeeScriptコンパイラプロジェクト（バージョン2.7.0）の非機能要件を定義するものである。CoffeeScriptはJavaScriptにコンパイルされるプログラミング言語であり、Node.js環境およびブラウザ環境の両方で動作するコンパイラを提供する。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| 単一ファイルコンパイル | 数百ms以内 | ソースコードサイズに依存。ベンチマーク処理（Lex、Rewrite、Parse、Compile）の合計時間 |
| REPL応答 | 即時（100ms以内） | インタラクティブな対話環境での応答性を維持 |
| ファイル変更検知（watchモード） | 25ms待機後にコンパイル | `command.coffee`の`wait`関数で25ms〜100msの待機時間を設定 |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 同時コンパイルファイル数 | 制限なし | ディレクトリ再帰コンパイル対応、`node_modules`は自動除外 |
| REPL同時実行 | 1セッション | シングルスレッドのNode.js環境で動作 |
| コマンド履歴サイズ | 最大10,240バイト | `repl.coffee`の`historyMaxInputSize`で設定 |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | N/A（コマンドラインツール） | 常駐サービスではないため稼働率の概念は適用外 |
| 計画停止時間 | N/A | オフラインツールのため該当なし |
| 障害復旧時間（RTO） | 即時 | コンパイルエラー時は詳細なエラーメッセージを表示して処理を継続または終了 |
| 目標復旧時点（RPO） | N/A | 状態を持たないツールのため該当なし |

## セキュリティ要件

### 入力検証

- CoffeeScriptソースコードの構文解析時、不正なエスケープシーケンスを検出してエラーを報告
- 8進数エスケープシーケンス（`\0x`形式）は禁止されており、エラーとして報告
- Unicode コードポイントエスケープ（`\u{xxxxx}`形式）は`0x10ffff`を超える値は禁止

### コード実行の安全性

- `eval`関数使用時はサンドボックス環境（`vm.runInContext`）での実行をサポート
- グローバルスコープ汚染を防ぐため、コンパイル時に`bare`オプションで関数ラッパーを制御可能
- ブラウザ環境では`window.eval`を使用してクリーンなグローバルスコープで評価

### 依存関係のセキュリティ

- 必須依存関係なし（ランタイム依存パッケージゼロ）
- トランスパイル機能使用時のみ`@babel/core`が必要
- 開発依存パッケージ（devDependencies）は最小限に維持

### ファイルシステムアクセス

- 読み込み: 指定されたソースファイルおよびディレクトリのみ
- 書き込み: `-o`オプションで指定された出力先、または入力ファイルと同じディレクトリ
- `node_modules`ディレクトリは自動的にスキップ

## 拡張性要件

### 言語機能の拡張性

- Jison（JavaScript用パーサジェネレータ）を使用した文法定義により、言語機能の追加が可能
- ASTノードの追加・変更は`nodes.coffee`で管理
- Rewriterパターンによるトークン変換ルールの追加が可能

### ツールチェーン統合

- Babel統合による最新JavaScript機能へのトランスパイルをサポート
- ソースマップ生成（v3形式）によるデバッグツール連携
- Webpack、Browserify等のバンドラーとの統合をサポート

### プラットフォーム拡張性

- Node.js 6以上での動作を保証（`package.json`の`engines`で定義）
- ブラウザ環境向けのコンパイラ（ES Module形式およびレガシースクリプト形式）を提供
- CommonJS、AMD、ESモジュール形式での配布をサポート

## 保守性要件

### コード品質

- 自己ホスティング: CoffeeScriptコンパイラ自身がCoffeeScriptで記述
- Literate CoffeeScript形式でのドキュメント統合コードをサポート
- 各ソースファイルにコメントによる詳細な説明を記載

### テスト要件

- 包括的なテストスイート（50+個のテストファイル）
- 非同期テストのサポート（Promise対応）
- ブラウザテスト（Puppeteer使用）
- 統合テスト（Webpack統合テスト含む）
- 機能別テスト（async/await、ジェネレータ、exponentiation等の新機能）

### ビルドシステム

- Cakefileによるビルドタスク管理
- `build`、`test`、`doc`等の明確なタスク分離
- `watch`モードによる開発時の自動リビルド

### ドキュメント

- Doccoによる注釈付きソースコードドキュメント生成
- Markdown形式のドキュメントセクション管理
- バージョン別ドキュメント（v1、v2）の管理

## 運用・監視要件

### ログ出力

- コンパイルエラー時の詳細なエラーメッセージ
  - ファイル名、行番号、列番号を含む位置情報
  - エラー箇所のコード抜粋とマーカー表示
  - カラー対応TTY環境での色付きエラー出力
- `--watch`モード時のタイムスタンプ付きログ出力
- スタックトレースのソースマップ対応（`patchStackTrace`関数）

### コマンドラインインターフェース

- 標準的なオプションパーサー（`optparse.coffee`）
- ヘルプメッセージ（`-h`/`--help`）
- バージョン表示（`-v`/`--version`）
- 詳細なオプション説明

### REPL機能

- コマンド履歴の永続化（`~/.coffee_history`）
- マルチラインモード（Ctrl-V）
- `.history`コマンドによる履歴表示
- SIGINT（Ctrl-C）ハンドリング

### エラーハンドリング

- 構文エラー: 詳細な位置情報と説明メッセージ
- ファイル未検出: 明確なエラーメッセージとプロセス終了
- 権限エラー（EPERM）: 適切な例外処理
- ファイル変更検知エラー: 自動リトライ機構

## 環境要件

### ランタイム要件

| 項目 | 要件 |
| --- | --- |
| Node.js | バージョン6以上 |
| ブラウザ | ES2015対応ブラウザ（モダン版）、ES5対応ブラウザ（レガシー版） |

### 開発環境要件

| 項目 | 要件 |
| --- | --- |
| @babel/core | トランスパイル機能使用時に必要（オプション） |
| jison | パーサ生成時に必要 |
| puppeteer | ブラウザテスト実行時に必要 |

## 備考

### 制限事項

1. マルチスレッド処理は非対応（Node.jsシングルスレッドモデルに依存）
2. ストリーミングコンパイルは非対応（ファイル全体を読み込んでからコンパイル）
3. インクリメンタルコンパイルは非対応（変更検知時は対象ファイル全体を再コンパイル）

### 非機能要件の検証方法

- 性能: `cake bench`タスクによるベンチマーク実行
- テスト: `cake test`タスクによるテストスイート実行
- ブラウザ互換性: `cake test:browser`タスクによるブラウザテスト
- 統合: `cake test:integrations`タスクによるWebpack統合テスト
