# 通知設計書 116-hintGlobalVar

## 概要

本ドキュメントは、Nimコンパイラにおける`hintGlobalVar`（グローバル変数ヒント）通知の設計について記述する。

### 本通知の処理概要

`hintGlobalVar`は、グローバル変数が宣言された際に開発者にその位置を通知するためのヒント通知である。グローバル変数の使用はマルチスレッド環境での問題や、コードの保守性低下につながる可能性があるため、その存在を明示的に示す。

**業務上の目的・背景**：グローバル変数はプログラムの状態管理を複雑にし、特にマルチスレッド環境では競合状態やデータ競合の原因となりうる。このヒントを通じて、開発者がグローバル変数の存在を認識し、必要に応じてローカル変数や依存性注入などの代替手法を検討できるようにする。

**通知の送信タイミング**：セマンティック解析フェーズ（semstmts.nim）において、変数宣言（var文）がグローバルスコープかつスレッドローカルでない場合に送信される。

**通知の受信者**：コンパイルを実行している開発者。コンソール出力またはIDE経由でメッセージを受け取る。

**通知内容の概要**：「global variable declared here」というメッセージと、変数の宣言位置が通知される。

**期待されるアクション**：開発者はグローバル変数の使用が意図的かどうかを確認し、必要に応じてスコープの見直しやスレッドローカル化（{.threadvar.}）を検討する。

## 通知種別

コンパイラ出力（コンソール / IDE統合）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 低（Hint） |
| リトライ | なし |

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

コンパイラの標準出力または標準エラー出力へ送信。verbosity レベル1以下ではデフォルトで無効化されている。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 送信元 | Nimコンパイラ |
| 形式 | テキスト |

### 本文テンプレート

```
Hint: global variable declared here [GlobalVar]
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | 固定メッセージ | MsgKindToStr | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 変数宣言解析 | semVar関数 | v.flags * {sfGlobal, sfThread} == {sfGlobal} | グローバルかつスレッドローカルでない場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| verbosity <= 1 | デフォルトのverbosityレベルでは抑止 |
| hintGlobalVar not in conf.notes | ヒントが無効化されている場合 |
| sfThread in v.flags | スレッドローカル変数の場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[semVar関数呼び出し] --> B[変数宣言解析]
    B --> C{sfGlobal in flags?}
    C -->|Yes| D{sfThread in flags?}
    C -->|No| G[ヒントなし]
    D -->|No| E[hintGlobalVar発行]
    D -->|Yes| G
    E --> F[suggestSym呼び出し]
    F --> H[終了]
    G --> H
```

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

### 参照テーブル一覧

該当なし（コンパイラ内部処理のみ）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | このヒント自体はエラーを発生させない | - |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限 | なし |

### 配信時間帯

制限なし

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

変数名は出力されないため、機密性への影響は限定的。ファイルパスと行番号は出力される。

## 備考

- verbosity レベル2以上で有効になる
- `--hint:GlobalVar:on/off`オプションで個別に制御可能
- スレッドローカル変数（{.threadvar.}）には通知されない

---

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

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

### 推奨読解順序

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

まず、通知の定義と設定について理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lineinfos.nim | `compiler/lineinfos.nim` | TMsgKind列挙型のhintGlobalVar定義（113行目）、MsgKindToStr配列でのメッセージテンプレート（239行目） |

**読解のコツ**: hintGlobalVarは固定メッセージ「global variable declared here」を持ち、変数名は出力されない。

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

処理の起点となる変数宣言処理を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | semstmts.nim | `compiler/semstmts.nim` | semVar関数内でのhintGlobalVar発行（985-986行目） |

**主要処理フロー**:
1. **985行目**: `v.flags * {sfGlobal, sfThread} == {sfGlobal}`の条件確認
2. **986行目**: `message(c.config, v.info, hintGlobalVar)`でヒント発行

#### Step 3: verbosity設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | lineinfos.nim | `compiler/lineinfos.nim` | computeNotesVerbosity関数（263-271行目）、レベル1からhintGlobalVarを除外（269行目） |

**主要処理フロー**:
- **269行目**: result[1]からhintGlobalVarを除外（つまりレベル2以上で有効）

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

```
semStmt (セマンティック解析)
    │
    └─ semVar (変数宣言解析)
           │
           ├─ フラグ確認 (sfGlobal, sfThread)
           │
           └─ message(hintGlobalVar)
```

### データフロー図

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

var宣言 ────────────────▶ semVar ───────────────▶ ヒント出力
    │                        │                    "global variable
    │                        │                     declared here"
    │                        │
sfGlobal, sfThread ─────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | TMsgKind定義、メッセージテンプレート、verbosity設定 |
| semstmts.nim | `compiler/semstmts.nim` | ソース | 変数宣言のセマンティック解析、hintGlobalVar発行 |
| msgs.nim | `compiler/msgs.nim` | ソース | メッセージ送信処理 |
