# 開発者ガイド

## 1. 概要

このガイドは、`tree-sitter-analyzer`プロジェクトへの貢献を目指す開発者向けに、プロジェクトの構造、コーディング規約、および開発ワークフローのベストプラクティスを提供します。

## 2. プロジェクト構造

プロジェクトは主に以下のディレクトリで構成されています。

- `tree_sitter_analyzer/`: メインのソースコード
    - `core/`: 解析エンジンやクエリサービスなどの中核機能
    - `languages/`: 各プログラミング言語のプラグイン
    - `formatters/`: 出力フォーマットを処理するクラス
    - `mcp/`: Model Context Protocol（MCP）サーバーの実装
    - `cli/`: コマンドラインインターフェースの実装
- `tests/`: 各種テストコード
- `docs/`: プロジェクト関連ドキュメント
- `examples/`: ライブラリの使用例を示すサンプルコード

## 3. 開発ワークフロー

一般的な開発フローは以下の通りです。

1. `main`ブランチから最新の変更を取得します。
2. 機能追加やバグ修正のための新しいブランチを作成します（例: `feature/new-parser`, `fix/query-bug`）。
3. コードを修正・追加し、関連するテストを作成または更新します。
4. `pre-commit`フックを実行して、コーディングスタイルと静的解析をチェックします。
5. プルリクエストを作成し、レビューを受けます。
6. 承認後、`main`ブランチにマージします。

## 4. 型安全性のベストプラクティス

当プロジェクトでは、コードの品質と保守性を高めるために、`mypy`を使用した静的型チェックを重視しています。開発時には以下のベストプラクティスに従ってください。

### 基本的な原則
- **すべての関数に型注釈を**: 関数の引数と戻り値には、必ず型注釈を付けてください。
  ```python
  # 良い例
  def get_user(user_id: int) -> User | None:
      # ...
      return user
  ```
- **`Any`の使用を避ける**: `Any`型は型チェックを無効化するため、可能な限り使用を避けてください。どうしても必要な場合にのみ、その理由をコメントで明記してください。
- **`Optional`を適切に使う**: `None`を返す可能性がある場合は、必ず`Optional[T]`または`T | None`を使用してください。
- **複雑な型には`TypeAlias`を**: 辞書やリストなどの複雑な型が繰り返し現れる場合は、`TypeAlias`を使用して可読性を高めてください。
  ```python
  from typing import TypeAlias

  UserDict: TypeAlias = dict[str, str | int]

  def process_user_data(data: UserDict) -> None:
      # ...
  ```

### mypy設定と実行
- **設定ファイル**: mypyの設定は`pyproject.toml`内の`[tool.mypy]`セクションで管理されています。
- **実行方法**: 開発中は、以下のコマンドでいつでも型チェックを実行できます。
  ```bash
  mypy tree_sitter_analyzer/
  ```
- **エラーへの対処**: mypyエラーが検出された場合は、コードを修正してエラーを解消してください。意図的な型違反（例: 動的なプラグイン読み込みなど）でエラーを無視する必要がある場合は、`# type: ignore[error-code]`コメントを使用し、その理由を簡潔に説明してください。

## 5. テスト

- **テストの実行**: プロジェクト全体のテストは`pytest`を使用して実行します。
  ```bash
  pytest
  ```
- **カバレッジ**: コードの変更には、可能な限り高いテストカバレッジを維持することが求められます。

---
このガイドは、プロジェクトの成長に合わせて継続的に更新されます。