# Issue #23: mypy トラブルシューティングのドキュメント追加

## 優先度: 低（当初想定より軽微）

## 概要

レビュアーから「mypyでrailwayがスキップされる」との報告があったが、調査の結果 **py.typed は wheel に正しく含まれている**。レビュアーの環境特有の問題か、他の原因がある可能性。

## 調査結果（2026-01-19）

### ビルド確認
```bash
$ uv build
Successfully built dist/railway_framework-0.8.1-py3-none-any.whl

$ unzip -l dist/railway_framework-0.8.1-py3-none-any.whl | grep py.typed
       60  2020-02-02 00:00   railway/py.typed
```

**→ py.typed は wheel に含まれている ✅**

### レビューでの報告
```
Skipping analyzing "railway": module is installed, but missing library stubs or py.typed marker
```

## 原因の可能性

### 1. レビュアーが古いバージョンを使用（最有力）
- v0.8.0 以前には py.typed がなかった
- pip cache に古いバージョンが残っている可能性

### 2. editable install の問題
- `pip install -e .` でインストールした場合、py.typed が認識されない可能性
- hatchling の editable install の挙動に依存

### 3. mypy キャッシュの問題
- `.mypy_cache/` に古い情報がキャッシュされている

## 再現手順（レビュアーへの確認依頼）

```bash
# 1. クリーンインストール
pip uninstall railway-framework -y
pip cache purge
pip install railway-framework

# 2. mypy キャッシュクリア
rm -rf .mypy_cache/

# 3. 確認
python -c "import railway; from pathlib import Path; print((Path(railway.__file__).parent / 'py.typed').exists())"
# → True であれば正常

# 4. mypy 実行
mypy --version
mypy your_code.py
```

## 対応方針

### Option A: Issue クローズ（検証済み）

py.typed は正しく配布されているため、Issue をクローズし、レビュアーに再インストールを依頼。

### Option B: ドキュメント追加

README または TUTORIAL に mypy 設定のトラブルシューティングを追加:

```markdown
## mypy で型チェックが効かない場合

1. パッケージを再インストール:
   ```bash
   pip uninstall railway-framework && pip install railway-framework
   ```

2. mypy キャッシュをクリア:
   ```bash
   rm -rf .mypy_cache/
   ```
```

### Option C: 追加テストの強化

CI で mypy 認識を検証するテストを追加:

```python
def test_mypy_recognizes_railway():
    """mypy should recognize railway as typed package."""
    import subprocess
    result = subprocess.run(
        ["mypy", "-c", "import railway; reveal_type(railway.node)"],
        capture_output=True,
        text=True,
    )
    # Should not contain "Skipping analyzing"
    assert "Skipping analyzing" not in result.stderr
```

## 推奨: Option A（クローズ）+ Option B（ドキュメント追加）

調査の結果、py.typed は正しく含まれている。レビュアーの環境問題と推定されるが、同様の問題に遭遇するユーザーのためにトラブルシューティングをドキュメントに追加。

## 受け入れ条件

- [x] py.typed が wheel に含まれていることを確認
- [ ] README または TUTORIAL にトラブルシューティングを追加
- [ ] レビュアーに再確認を依頼

## 関連

- Issue #17: py.typed追加（完了）
- レビュー4（v0.8.1）: 型安全性 6/10
