# 通知設計書 104-hintPath

## 概要

本ドキュメントは、Nimコンパイラの`hintPath`ヒント通知に関する設計を定義する。このヒントは、検索パスに追加されたディレクトリを通知するものである。

### 本通知の処理概要

`hintPath`ヒントは、Nimコンパイラがモジュール検索パスにディレクトリを追加した際に、そのパスを開発者に通知するヒントメッセージである。

**業務上の目的・背景**：Nimコンパイラはモジュールのインポート時に複数の検索パスを参照する。Nimbleパッケージのパスが追加される際などにこのヒントが出力され、開発者はどのディレクトリが検索対象に含まれているかを把握できる。これにより、モジュールが見つからない問題や、意図しないモジュールが読み込まれる問題のデバッグが容易になる。

**通知の送信タイミング**：Nimbleパッケージのパスが遅延パス（lazyPaths）に追加される際に送信される。主にNimbleパッケージディレクトリの走査時（nimblePath関数経由）に発生する。

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

**通知内容の概要**：「added path: '$1'」という形式で、$1に追加されたパスが代入される。

**期待されるアクション**：開発者は追加されたパスを確認し、期待するパッケージディレクトリが検索パスに含まれているか検証する。問題がある場合はNimble設定やプロジェクト設定を見直す。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| メッセージ種別 | Hint |
| フォーマット | `Hint: added path: '{パス}' [Path]` |
| 色 | 緑色（HintColor = fgGreen） |

### 本文テンプレート

```
Hint: added path: '/home/user/.nimble/pkgs/package-0.1.0' [Path]
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| $1 | 追加されたパス | Nimbleパッケージディレクトリ | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コンパイル処理 | Nimbleパス追加 | `hintPath in conf.notes`（verbosity >= 2） | lazyPathsへのパス追加時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| verbosity < 2 | デフォルトでは非表示（NotesVerbosity[1]から除外） |
| optHints not in conf.options | ヒント出力自体が無効化されている場合 |
| パスが既に追加済み | searchPathsに既に含まれている場合は追加しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[nimblePath関数呼び出し] --> B[addPathRec: パッケージディレクトリ走査]
    B --> C[addPackage: 有効なパッケージを収集]
    C --> D{各パッケージ}
    D --> E[addNimblePath呼び出し]
    E --> F{searchPathsに既存?}
    F -->|Yes| G[スキップ]
    F -->|No| H[message hintPath]
    H --> I[conf.lazyPaths.insert]
    I --> J{次のパッケージあり?}
    G --> J
    J -->|Yes| D
    J -->|No| K[終了]
```

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

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

### 参照データ

| データ | 用途 | 備考 |
|--------|------|------|
| conf.searchPaths | 既存の検索パス確認 | 重複チェック用 |
| conf.lazyPaths | 遅延読み込みパス | 追加先 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | このヒントは情報出力のみ | - |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限なし | パッケージの数だけ出力される可能性あり |

### 配信時間帯

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

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

- パッケージパスにはユーザー名などのシステム情報が含まれる可能性がある
- CI/CDログに出力される場合、システムパス情報が漏洩する可能性に注意

## 備考

- verbosity 2以上または`--hint:Path:on`オプションで有効化可能
- Nimbleパッケージのバージョンやチェックサムがパスに含まれることがある
- `.nimble-link`ファイルが存在する場合、そのリンク先がパスとして使用される

---

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

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

### 推奨読解順序

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

通知種別の定義とパス管理の仕組みを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lineinfos.nim | `compiler/lineinfos.nim` | TMsgKind列挙型でhintPathの定義を確認（109行目） |
| 1-2 | lineinfos.nim | `compiler/lineinfos.nim` | MsgKindToStr配列でメッセージ文字列を確認（227行目） |
| 1-3 | lineinfos.nim | `compiler/lineinfos.nim` | NotesVerbosity[1]からhintPathが除外されていることを確認（268行目） |

**読解のコツ**: hintPathはverbosity 2以上で有効になるため、NotesVerbosity配列の設定を確認することが重要。

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

Nimbleパス追加処理の起点を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | nimblecmd.nim | `compiler/nimblecmd.nim` | addNimblePath関数（139-153行目）でhintPath出力処理を確認 |
| 2-2 | nimblecmd.nim | `compiler/nimblecmd.nim` | nimblePath関数（165-171行目）でパス追加の全体像を理解 |

**主要処理フロー**:
1. **139行目**: `addNimblePath`関数開始
2. **141-147行目**: `.nimble-link`ファイルの処理
3. **151行目**: `searchPaths`に既存かチェック
4. **152行目**: `message(conf, info, hintPath, path)`でヒント出力
5. **153行目**: `conf.lazyPaths.insert`でパス追加

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | msgs.nim | `compiler/msgs.nim` | message関数（641-642行目）でメッセージ出力処理 |

**主要処理フロー**:
- **641-642行目**: `message`テンプレートがliMessageを呼び出す

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

```
nimblePath (nimblecmd.nim 165行目)
    │
    ├─ addPathRec (155行目)
    │      ├─ walkDir: パッケージディレクトリ走査
    │      ├─ addPackage: 有効なパッケージを収集
    │      └─ addNimblePath呼び出し
    │
    └─ addNimblePath (139行目)
           │
           ├─ .nimble-link処理
           │
           ├─ searchPaths重複チェック
           │
           ├─ message(hintPath) ← ここでhintPath出力
           │      └─ liMessage → styledMsgWriteln
           │
           └─ lazyPaths.insert
```

### データフロー図

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

Nimbleパッケージ ───▶ nimblePath           ───▶ パッケージ一覧
ディレクトリ             │
                        ▼
                   addPathRec            ───▶ 有効なパッケージ抽出
                        │
                        ▼
                   addNimblePath         ───▶ stderr/stdout
                        │                      "Hint: added path: ..."
                        ▼
                   lazyPaths.insert      ───▶ conf.lazyPaths更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | メッセージ種別定義（TMsgKind列挙型） |
| nimblecmd.nim | `compiler/nimblecmd.nim` | ソース | Nimbleパス管理、hintPath出力 |
| msgs.nim | `compiler/msgs.nim` | ソース | メッセージ出力処理 |
| options.nim | `compiler/options.nim` | ソース | searchPaths, lazyPaths管理 |
