# 機能設計書 69-型注釈

## 概要

本ドキュメントは、CoffeeScriptの型注釈（Type Annotations）機能の設計を記述する。型注釈は、Flowの[Comment Types](https://flow.org/en/docs/types/comments/)構文を使用して、静的型チェックのための型情報をCoffeeScriptコードに追加する言語機能である。

### 本機能の処理概要

CoffeeScriptの型注釈は、ブロックコメント（`### ###`）内にFlowスタイルの型定義を記述することで実現される。CoffeeScript自体は型チェックを行わず、生成されたJavaScriptコードをFlowに渡すことで型チェックが実行される。この方式により、CoffeeScriptの簡潔な構文を維持しながら、静的型チェックの恩恵を受けることができる。

**業務上の目的・背景**：
大規模なJavaScriptプロジェクトでは、静的型チェックによるバグの早期発見やIDEの補完機能の向上が重要である。TypeScriptが広く普及している中、CoffeeScriptでもFlowを使用した型チェックを可能にすることで、型安全性を確保しながらCoffeeScriptの開発体験を維持できる。

**機能の利用シーン**：
- 関数パラメータへの型注釈（例：`fn = (str ###: string ###) ->`）
- 戻り値の型注釈（例：`fn = () ###: number ### ->`）
- 型定義（例：`###:: type MyType = {...} ###`）
- オブジェクト型の定義
- ジェネリクスの使用
- Flowの`@flow`プラグマの追加

**主要な処理内容**：
1. `###`ブロックコメント内の型注釈を保持
2. `###:`（インライン型）と`###::`（型定義ブロック）の区別
3. コメントとして出力し、Flow互換の形式を維持
4. `--bare --no-header`オプションで`// @flow`を先頭に配置可能に
5. パラメータリストや関数シグネチャでの型注釈位置の維持

**関連システム・外部連携**：
型注釈はCoffeeScriptのコメント処理として扱われ、生成されるJavaScriptにはFlowのComment Types形式でそのまま出力される。その後、Flowツールチェーンで型チェックを実行する。

**権限による制御**：
本機能はコンパイル時の言語機能であり、権限による制御は適用されない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面関連なし（言語機能） |

## 機能種別

言語構文変換 / 型システム連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| content | String | Yes | 型注釈のコメント内容 | - |
| here | Boolean | Yes | ブロックコメント（`###`）かどうか | - |
| typeAnnotation | Boolean | No | 型注釈コメントかどうか | - |

### 入力データソース

CoffeeScriptソースコード内の`###`ブロックコメント

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| JavaScript | String | Flowの/*: */または/*:: */形式のコメント |

### 出力先

JavaScriptコード（標準出力またはファイル）

## 処理フロー

### 処理シーケンス

```
1. ブロックコメントの検出
   └─ Lexer.commentToken()で`###`を検出
2. 型注釈の判定
   └─ コメント開始が`::`または`:`で始まるか確認
3. コメントの保持
   └─ hereコメントとしてトークンに付加
4. コンパイル処理
   └─ 4.1 通常のコメントとして出力
   └─ 4.2 Flow互換の`/* */`形式に変換
5. Flowでの処理
   └─ 生成されたJavaScriptをFlowで型チェック
```

### フローチャート

```mermaid
flowchart TD
    A[###コメント開始] --> B{先頭が::?}
    B -->|Yes| C[型定義ブロック]
    B -->|No| D{先頭が:?}
    D -->|Yes| E[インライン型注釈]
    D -->|No| F[通常のコメント]
    C --> G[hereコメントとして保持]
    E --> G
    F --> G
    G --> H[JavaScriptコンパイル]
    H --> I[/* */形式で出力]
    I --> J[Flowで型チェック]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-69-1 | ブロックコメント限定 | 型注釈は`###`ブロックコメントでのみ使用可能 | - |
| BR-69-2 | @flowプラグマ | ファイル先頭に`# @flow`を記述 | Flowで型チェックする場合 |
| BR-69-3 | --bareオプション | `// @flow`を先頭に配置するには`--bare`が必要 | - |
| BR-69-4 | インライン配置 | 型注釈はパラメータや変数の直後に配置 | - |
| BR-69-5 | Comment Types形式 | Flowの[Comment Types](https://flow.org/en/docs/types/comments/)形式で出力 | - |

### 計算ロジック

特になし（コメントの透過的な変換）

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

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Flowエラー | 型が一致しない | 型注釈を修正 |
| - | Flowエラー | 型定義が不正 | Flow構文に従った型定義を記述 |

### リトライ仕様

コンパイル時にはエラーは発生しない。型エラーはFlow実行時に検出される。

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

本機能はデータベーストランザクションを使用しない。

## パフォーマンス要件

- コンパイル時間: 通常のコメントと同等
- 型チェック時間: Flowの処理に依存

## セキュリティ考慮事項

- 型注釈はランタイムに影響しない（コメントとして出力）
- 型安全性はFlowの責務

## 備考

- CoffeeScript自体は型チェックを行わない
- TypeScript型注釈は非サポート
- FlowのComment Types構文に準拠
- Node.js v10以上を推奨（Flow実行時）

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: ドキュメントと例を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | type_annotations.md | `documentation/sections/type_annotations.md` | 型注釈機能の説明 |
| 1-2 | type_annotations.coffee | `documentation/examples/type_annotations.coffee` | 使用例 |

**読解のコツ**:
- `# @flow`でFlowを有効化
- `###:: ... ###`で型定義
- `###: type ###`でインライン型注釈

**主要処理フロー**:
1. ファイル先頭に`# @flow`プラグマ
2. `###:: type Obj = {...} ###`で型定義
3. `(str ###: string ###, obj ###: Obj ###)`でパラメータ型
4. `) ###: string ###`で戻り値型

#### Step 2: Lexerのコメント処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | lexer.coffee | `src/lexer.coffee` | commentTokenメソッド |

**読解のコツ**:
- `###`で始まるコメントは`hereComment`として処理
- コメントの内容はそのまま保持される
- Flowの型注釈構文はコメントとして透過的に扱われる

#### Step 3: Parensノードの特殊処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | nodes.coffee | `src/nodes.coffee` | Parensクラスのコメント処理（5149-5166行目） |

**主要処理フロー**:
- **5155-5156行目**: ブロックコメントが識別子の後に続く場合の特殊処理
- Flow型注釈のために括弧を維持する必要がある場合の判定

### プログラム呼び出し階層図

```
CoffeeScript.compile()
    │
    ├─ Lexer.tokenize()
    │      └─ commentToken()
    │             └─ ### コメントを検出
    │                    └─ hereComment として保持
    │
    ├─ parser.parse()
    │      └─ コメントをノードに付加
    │
    └─ compileNode()
           └─ /* */ 形式でコメント出力
                  │
                  ▼
           [Flow による型チェック]
```

### データフロー図

```
[入力]                          [処理]                              [出力]

CoffeeScript           Lexer           Compiler              Flow
型注釈コメント     →  トークン    →   JavaScript      →    型チェック
                     (here)          コメント

例:
fn = (str ###: string ###) ###: string ### ->
  str.toUpperCase()
    ↓
[hereComment: ': string', hereComment: ': string']
    ↓
var fn = function(str /*: string */) /*: string */ {
  return str.toUpperCase();
};
    ↓
Flow: 型エラーなし ✓
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| type_annotations.md | `documentation/sections/type_annotations.md` | ドキュメント | 型注釈機能の説明 |
| type_annotations.coffee | `documentation/examples/type_annotations.coffee` | 例 | 使用例 |
| lexer.coffee | `src/lexer.coffee` | ソース | commentTokenメソッド |
| nodes.coffee | `src/nodes.coffee` | ソース | Parensのコメント処理（5149-5166行目） |
| helpers.coffee | `src/helpers.coffee` | ソース | コメント処理ヘルパー |
