# 通知設計書 107-hintName

## 概要

本ドキュメントは、Nimコンパイラの`hintName`ヒント通知に関する設計を定義する。このヒントは、識別子の命名規則（NEP1スタイル）違反を通知するものである。

### 本通知の処理概要

`hintName`ヒントは、Nimコンパイラのスタイルチェッカー（linter）機能により、識別子がNimの命名規則（NEP1: Nim Enhancement Proposal 1）に準拠していない場合に出力される通知である。

**業務上の目的・背景**：Nimには推奨される命名規則（NEP1）が存在し、型名はPascalCase、変数・関数名はcamelCaseで記述することが推奨されている。この通知により、開発者はコードの一貫性と可読性を維持でき、チーム開発においてコーディングスタイルの統一を図ることができる。また、Nimの標準ライブラリとの整合性も保たれる。

**通知の送信タイミング**：セマンティック解析フェーズで識別子の定義または使用が検出された際、スタイルチェックオプションが有効で、識別子がNEP1規則に準拠していない場合に送信される。

**通知の受信者**：コンパイル実行者（開発者）がコンソール出力（stderr）を通じてこの通知を受信する。

**通知内容の概要**：「'$1' should be: '$2'」という形式で、$1に現在の識別子、$2に推奨される命名が代入される。

**期待されるアクション**：開発者はこの通知を確認し、識別子の命名を推奨されるスタイルに修正する。意図的に異なる命名を使用している場合は、`--styleCheck:off`オプションで無効化できる。

## 通知種別

コンソール出力（コンパイラヒント）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（コンパイルプロセス内で即時出力） |
| 優先度 | 低（ヒント情報） |
| リトライ | 無し |

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

標準エラー出力（stderr）に送信される。`--stdout`オプションが指定されている場合は標準出力（stdout）に送信される。`writelnHook`が設定されている場合は、そのフック関数に委譲される。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| メッセージ種別 | Hint（または設定によりWarning/Error） |
| フォーマット | `Hint: '{現在名}' should be: '{推奨名}' [Name]` |
| 色 | 緑色（HintColor = fgGreen）、設定によりWarning/Error色 |

### 本文テンプレート

```
Hint: 'my_variable' should be: 'myVariable' [Name]
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| $1 | 現在の識別子名 | ソースコードの識別子 | Yes |
| $2 | 推奨される識別子名 | beautifyName関数の結果 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| セマンティック解析 | 識別子定義/使用 | `optStyleCheck in conf.options` かつ `hintName in conf.notes` | スタイルチェック有効時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| optStyleCheck not in conf.options | スタイルチェックが無効 |
| hintName not in conf.notes | 名前チェックが無効 |
| 外部パッケージのシンボル | belongsToProjectPackageMaybeNilでチェック |
| result変数 | 特殊変数は除外 |
| 一時変数（skTemp） | コンパイラ生成変数は除外 |
| FFIシンボル（sfImportc/sfExportc） | 外部インターフェースは除外 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[セマンティック解析: 識別子検出] --> B{optStyleCheck有効?}
    B -->|No| C[スキップ]
    B -->|Yes| D{hintName in conf.notes?}
    D -->|No| C
    D -->|Yes| E{プロジェクトパッケージ?}
    E -->|No| C
    E -->|Yes| F{除外対象?}
    F -->|Yes| C
    F -->|No| G[beautifyName: 推奨名生成]
    G --> H{現在名 != 推奨名?}
    H -->|No| C
    H -->|Yes| I[lintReport呼び出し]
    I --> J[liMessage出力]
```

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

該当なし（ファイルシステムやデータベースへのアクセスなし）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | このヒントは情報出力のみ（設定によりエラー化可能） | - |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限なし | 違反が検出されるたびに出力 |

### 配信時間帯

制限なし（コンパイル実行時に即時出力）

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

- 識別子名がログに出力されるが、通常は機密性の低い情報

## 備考

- `--styleCheck:hint`でヒント出力、`--styleCheck:error`でエラー化可能
- `--styleCheck:usages`で使用箇所のみチェック、`--styleCheck:off`で無効化
- NEP1規則:
  - 型名: PascalCase
  - 変数/関数名: camelCase
  - 定数/列挙値: camelCaseまたはPascalCase
- 一部の組み込み型（int, string等）は例外として小文字が許容される

---

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

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

### 推奨読解順序

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

通知種別の定義とスタイルチェックの仕組みを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lineinfos.nim | `compiler/lineinfos.nim` | TMsgKind列挙型でhintNameの定義を確認（110行目） |
| 1-2 | lineinfos.nim | `compiler/lineinfos.nim` | MsgKindToStr配列でメッセージ文字列を確認（230行目） |

**読解のコツ**: hintNameは"Name"という短縮名を持ち、出力時には[Name]として表示される。

#### Step 2: スタイルチェッカーを理解する

スタイルチェック処理の核心部分を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | linter.nim | `compiler/linter.nim` | beautifyName関数（31-76行目）で推奨名生成ロジックを理解 |
| 2-2 | linter.nim | `compiler/linter.nim` | styleCheckDef テンプレート（95-109行目）で定義時チェックを理解 |
| 2-3 | linter.nim | `compiler/linter.nim` | styleCheckUse テンプレート（137-145行目）で使用時チェックを理解 |

**主要処理フロー**:
1. **31-76行目**: `beautifyName`関数で識別子を正規化
2. **90-93行目**: `nep1CheckDefImpl`で実際の比較とレポート
3. **95-109行目**: `styleCheckDef`テンプレートで各種除外条件をチェック
4. **99行目**: `hintName in ctx.config.notes`でヒント有効性チェック

#### Step 3: メッセージ出力層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | msgs.nim | `compiler/msgs.nim` | lintReportテンプレート（665-670行目）でメッセージ出力処理 |

**主要処理フロー**:
- **669行目**: `hintName`がデフォルトのメッセージ種別として使用される

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

```
semExpr / semStmt (意味解析)
    │
    └─ styleCheckDef / styleCheckUse (linter.nim)
           │
           ├─ チェック条件の評価
           │   ├─ optStyleCheck in conf.options
           │   ├─ hintName in conf.notes
           │   └─ belongsToProjectPackageMaybeNil
           │
           ├─ 除外条件の評価
           │   ├─ skResult / skTemp 除外
           │   ├─ FFI シンボル除外
           │   └─ 匿名シンボル除外
           │
           └─ nep1CheckDefImpl / styleCheckUseImpl
                  │
                  ├─ beautifyName: 推奨名生成
                  │
                  └─ lintReport ← ここでhintName出力
                         └─ liMessage → styledMsgWriteln
```

### データフロー図

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

識別子           ───▶ styleCheckDef/Use    ───▶ チェック対象判定
(定義/使用)            │
                       ▼
                  beautifyName           ───▶ 推奨名
                       │
                       ▼
現在名 != 推奨名 ───▶ lintReport           ───▶ stderr/stdout
                       │                      "Hint: 'x' should be: 'y'"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | メッセージ種別定義（TMsgKind列挙型） |
| linter.nim | `compiler/linter.nim` | ソース | スタイルチェッカー本体、beautifyName、styleCheckDef/Use |
| msgs.nim | `compiler/msgs.nim` | ソース | lintReportテンプレート、メッセージ出力処理 |
| options.nim | `compiler/options.nim` | ソース | optStyleCheck, optStyleHint, optStyleErrorフラグ |
