# 通知設計書 74-warnEffect

## 概要

本ドキュメントは、Nimコンパイラの警告メッセージ「warnEffect」（エフェクトの警告）に関する通知設計書である。関数やプロシージャのエフェクト（例外発生、副作用など）が宣言されたエフェクト仕様と一致しない場合に、開発者に警告を発する機能について記載する。

### 本通知の処理概要

この通知は、Nimコンパイラがエフェクトチェック中に、実際の関数のエフェクトが`.raises`や`.effects`プラグマで宣言されたエフェクト仕様と矛盾することを検出した際に発行される警告メッセージである。

**業務上の目的・背景**：Nimのエフェクトシステムは、関数が発生させる可能性のある例外や副作用をコンパイル時に追跡する機能を提供する。`.raises: []`のように例外を発生させないことを宣言した関数が実際に例外を発生させる可能性がある場合、実行時の予期しない例外につながる。本警告は通常エラーとして発行されるが、特定の設定下では警告として発行され、コードの品質向上を促す。

**通知の送信タイミング**：コンパイル時、セマンティック解析第2パス（sempass2）において、関数のエフェクトチェック（checkRaisesSpec関数）が行われる際に、エフェクト仕様との不一致が検出された場合に発行される。

**通知の受信者**：Nimコンパイラを使用してコードをコンパイルしている開発者。警告メッセージは標準エラー出力またはコンパイラの設定に応じた出力先に送信される。

**通知内容の概要**：警告メッセージには、発生する可能性のある例外や副作用の詳細と、宣言されたエフェクト仕様との差異が含まれる。

**期待されるアクション**：開発者は警告を確認し、エフェクト仕様を実際の実装に合わせて更新するか、または実装を修正してエフェクト仕様に準拠させることが期待される。

## 通知種別

コンパイラ警告メッセージ（標準エラー出力/構造化出力）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（コンパイル時） |
| 優先度 | 中〜高（通常はError、設定によりWarning） |
| リトライ | なし |

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

コンパイラの標準エラー出力、または`--stdout`オプション指定時は標準出力に送信。`structuredErrorHook`が設定されている場合はフック関数を通じて送信される。

## 通知テンプレート

### コンパイラ警告出力の場合

| 項目 | 内容 |
|-----|------|
| 送信元 | Nimコンパイラ |
| 形式 | テキスト |
| 重大度 | Warning（emitWarningsがtrueの場合） |

### 本文テンプレート

```
{ファイルパス}({行番号}, {列番号}) Warning: {例外式} {メッセージ}{例外型} [Effect]
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| $1 | エフェクト詳細メッセージ | checkRaisesSpecからのmsg引数 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コンパイル時 | エフェクトチェック | エフェクト仕様との不一致 | checkRaisesSpec関数でspec vs realの比較 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| --warning:Effect:off | コマンドラインで明示的に無効化された場合 |
| {.warning[Effect]:off.} | プラグマで無効化された場合 |
| emitWarningsがfalse | エラーとして発行される場合（通常動作） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[関数のエフェクトチェック開始] --> B[checkRaisesSpec呼び出し]
    B --> C{spec vs real比較}
    C -->|一致| I[終了]
    C -->|不一致| D{emitWarningsフラグ}
    D -->|true| E[warnEffect発行]
    D -->|false| F[errGenerated発行]
    E --> G[message関数呼び出し]
    F --> G
    G --> H[出力先にメッセージ表示]
    H --> I
```

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

### 参照テーブル一覧

コンパイラはデータベースを使用せず、メモリ上のAST（抽象構文木）とシンボルテーブルを参照する。

### 内部データ構造

| 構造体 | 用途 | 備考 |
|--------|------|------|
| PNode | エフェクトリスト | spec（宣言）とreal（実際）を保持 |
| TLineInfo | 位置情報 | ファイル/行/列を保持 |
| ConfigRef | 設定 | 警告の有効/無効状態を保持 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| エラーとして発行 | emitWarningsがfalse（デフォルト） | コンパイル中断 |
| 警告として発行 | emitWarningsがtrue | 警告表示のみ |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

コンパイル実行時に即時発行

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

- ファイルパスが出力に含まれるため、センシティブなパス情報が漏洩する可能性がある
- エフェクトの不一致は予期しない例外発生につながり、セキュリティ上の脆弱性を引き起こす可能性がある

## 備考

- 通常はエラー（errGenerated）として発行されるが、特定の設定でwarnEffectとして警告に降格可能
- `.raises`プラグマと組み合わせて使用される
- エフェクトシステムはNimの型安全性の重要な構成要素

---

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

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

### 推奨読解順序

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

まず、警告の定義とエフェクトシステムの基本構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lineinfos.nim | `compiler/lineinfos.nim` | 87行目: warnEffectの定義を確認 |
| 1-2 | lineinfos.nim | `compiler/lineinfos.nim` | 196行目: メッセージテンプレート「$1」の定義を確認 |

**読解のコツ**: warnEffectはEffectという文字列キーに関連付けられている。

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

警告発行の起点となるエフェクトチェック処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sempass2.nim | `compiler/sempass2.nim` | 1603-1632行目: checkRaisesSpec関数の実装 |

**主要処理フロー**:
1. **1608行目**: usedセットの初期化
2. **1609行目**: realリストの各要素に対するイテレーション
3. **1610-1617行目**: specリストとのマッチング処理
4. **1619-1626行目**: 不一致時のメッセージ発行（1624行目でwarnEffectまたはerrGenerated）

#### Step 3: emitWarningsフラグを理解する

警告とエラーの切り替えロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sempass2.nim | `compiler/sempass2.nim` | 1624行目: `if emitWarnings: warnEffect else: errGenerated`の条件分岐 |

**読解のコツ**: emitWarningsパラメータがtrueの場合のみwarnEffectが使用される。

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

```
trackProc (sempass2.nim)
    │
    ├─ エフェクトリスト構築
    │      └─ spec: 宣言されたエフェクト
    │      └─ real: 実際のエフェクト
    │
    └─ checkRaisesSpec (sempass2.nim:1603)
           │
           ├─ effectPredicate (比較関数)
           │
           └─ message (msgs.nim:641)
                  └─ if emitWarnings: warnEffect
                     else: errGenerated
```

### データフロー図

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

関数AST ───▶ trackProc関数 ───▶ エフェクト警告/エラー
   │                   │                    │
   │                   ├─ エフェクト収集     ├─ warnEffect (警告)
   │                   │                    │
   └─ .raisesプラグマ  └─ checkRaisesSpec   └─ errGenerated (エラー)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | メッセージ種別とテンプレートの定義 |
| sempass2.nim | `compiler/sempass2.nim` | ソース | エフェクトチェックとcheckRaisesSpec関数 |
| msgs.nim | `compiler/msgs.nim` | ソース | メッセージ出力の実装 |
| ast.nim | `compiler/ast.nim` | ソース | エフェクトリストノードの定義 |
| pragmas.nim | `compiler/pragmas.nim` | ソース | .raisesプラグマの処理 |
