# 通知設計書 30-shebang line warning

## 概要

本ドキュメントは、CoffeeScriptコンパイラにおけるシバン行の引数警告（shebang line warning）の通知仕様を記述する。

### 本通知の処理概要

本通知は、CoffeeScriptスクリプトファイルのシバン行（`#!`で始まる行）に複数の引数が含まれている場合に発生する警告メッセージである。

**業務上の目的・背景**：Unix系システムでは、実行可能スクリプトの先頭にシバン行を記述することで、スクリプトの実行に使用するインタプリタを指定できる。しかし、Linuxなどの一部プラットフォームでは、シバン行で指定できる引数は1つまでに制限されており、複数の引数を指定するとスクリプトが正しく実行されない可能性がある。この警告を表示することで、クロスプラットフォームでの互換性問題を事前に通知する。

**通知の送信タイミング**：スクリプト実行時（`coffee script.coffee`）、ファイルの先頭行を検査するタイミングで発生する。コンパイルのみの場合（`--compile`オプション）では発生しない。

**通知の受信者**：CoffeeScriptスクリプトを実行しているユーザー。標準エラー出力に警告メッセージが出力される。

**通知内容の概要**：警告メッセージとして「The script to be run begins with a shebang line with more than one argument」が表示され、該当するシバン行の内容と引数リストが出力される。

**期待されるアクション**：開発者は、シバン行の引数を1つ以下に修正するか、`env`コマンドを使用した間接的な方法に変更する必要がある。

## 通知種別

コンソール警告出力（stderr）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（スクリプト実行前に即時出力） |
| 優先度 | 中（警告、処理は継続） |
| リトライ | なし |

### 送信先決定ロジック

スクリプト実行時に標準エラー出力（stderr）に警告メッセージを出力する。処理は中断されず、スクリプトの実行は継続される。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr |
| 形式 | テキスト |

### 本文テンプレート

```
The script to be run begins with a shebang line with more than one
argument. This script will fail on platforms such as Linux which only
allow a single argument.
The shebang line was: '{firstLine}' in file '{file}'
The arguments were: {argumentsList}
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| firstLine | シバン行の内容 | input.split(/$/m, 1)[0] | Yes |
| file | ファイル名 | 引数として渡されたファイル名 | Yes |
| argumentsList | 引数のJSON文字列 | JSON.stringify(args) | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| スクリプト実行 | シバン行解析 | args?.length > 1 | シバン行の引数が2つ以上ある場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 引数が1つ以下 | シバン行の引数が0個または1個の場合 |
| シバン行なし | ファイルがシバン行で始まらない場合 |
| コンパイルのみ | --compileオプションのみで実行の場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[スクリプト実行開始] --> B[ファイル読み込み]
    B --> C[checkShebangLine呼び出し]
    C --> D[先頭行を取得]
    D --> E{シバン行?}
    E -->|No| F[警告なし]
    E -->|Yes| G[引数を解析]
    G --> H{引数 > 1?}
    H -->|No| F
    H -->|Yes| I[console.error呼び出し]
    I --> J[警告メッセージ1出力]
    J --> K[console.error呼び出し]
    K --> L[シバン行情報出力]
    L --> M[console.error呼び出し]
    M --> N[引数情報出力]
    N --> O[スクリプト実行継続]
    F --> O
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（ファイルベースの処理）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | 警告のみ、エラーは発生しない | - |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | N/A（警告のみ） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限 | なし（スクリプト実行ごとに1回） |

### 配信時間帯

制限なし（スクリプト実行時に即時通知）

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

- 警告メッセージにはファイルパスとシバン行の内容が含まれる
- シバン行にはインタプリタのパスが含まれるため、システム構成情報が漏洩する可能性がある

## 備考

- この警告はCoffeeScript 2.0で導入された
- macOSではシバン行に複数引数を指定できるが、Linuxでは制限がある
- 推奨される解決策：`#!/usr/bin/env coffee`のような形式を使用

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

シバン行の解析ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | coffeescript.coffee | `src/coffeescript.coffee` | checkShebangLine関数（325-336行目） |

**読解のコツ**: シバン行は正規表現`/^#!\s*([^\s]+\s*)(.*)/`でパースされ、引数部分はスペースで分割される。

#### Step 2: エントリーポイントを理解する

シバン行チェックの呼び出しポイントを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | coffeescript.coffee | `src/coffeescript.coffee` | 69行目 - checkShebangLine呼び出し |

**主要処理フロー**:
1. **69行目**: `checkShebangLine filename, code`でチェック関数を呼び出し
2. この呼び出しはrunメソッド内で行われる

#### Step 3: シバン行解析処理を理解する

checkShebangLine関数の詳細を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | coffeescript.coffee | `src/coffeescript.coffee` | 325-336行目 - checkShebangLine関数 |

**主要処理フロー**:
1. **326行目**: `input.split(/$/m, 1)[0]`で先頭行を取得
2. **327行目**: 正規表現でシバン行をマッチング
3. **328行目**: 引数部分をスペースで分割、空文字をフィルタ
4. **329行目**: `args?.length > 1`で引数数をチェック
5. **330-336行目**: 警告メッセージを出力

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

```
coffee script.coffee
    │
    ├─ CoffeeScript.run()
    │      └─ checkShebangLine(filename, code)
    │             ├─ firstLine = input.split(/$/m, 1)[0]
    │             ├─ rest = firstLine.match(/^#!\s*([^\s]+\s*)(.*)/)
    │             ├─ args = rest[2].split(/\s/).filter(...)
    │             │
    │             └─ args.length > 1
    │                    ├─ console.error(警告メッセージ1)
    │                    ├─ console.error(シバン行情報)
    │                    └─ console.error(引数情報)
    │
    └─ スクリプト実行継続
```

### データフロー図

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

#!/usr/bin/env coffee -a -b  正規表現マッチング            警告メッセージ
...                               │                       "The script to
                                  ▼                        be run begins
firstLine:               args = ["-a", "-b"]               with a shebang
"#!/usr/bin/env                   │                        line with more
 coffee -a -b"                    ▼                        than one
                         args.length = 2 > 1               argument..."
                                  │
                                  ▼
                         console.error(...)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | checkShebangLine関数、シバン行解析 |
| invocation_argument_parsing.coffee | `test/invocation_argument_parsing.coffee` | テスト | テストケース（70-106行目） |
| importing/shebang_extra_args.coffee | `test/importing/shebang_extra_args.coffee` | テストデータ | 複数引数を持つシバン行のテストファイル |
| breaking_changes_argument_parsing_and_shebang_lines.md | `documentation/sections/breaking_changes_argument_parsing_and_shebang_lines.md` | ドキュメント | シバン行に関する仕様説明 |
