開発者ガイド

1. 概要

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

2. プロジェクト構造

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

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

3. 開発ワークフロー

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

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

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

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

基本的な原則

• すべての関数に型注釈を: 関数の引数と戻り値には、必ず型注釈を付けてください。

  # 良い例
  def get_user(user_id: int) -> User | None:
      # ...
      return user
  

• Anyの使用を避ける: Any型は型チェックを無効化するため、可能な限り使用を避けてください。どうしても必要な場合にのみ、その理由をコメントで明記してください。
• Optionalを適切に使う: Noneを返す可能性がある場合は、必ずOptional[T]またはT | Noneを使用してください。
• 複雑な型にはTypeAliasを: 辞書やリストなどの複雑な型が繰り返し現れる場合は、TypeAliasを使用して可読性を高めてください。

  from typing import TypeAlias
  
  UserDict: TypeAlias = dict[str, str | int]
  
  def process_user_data(data: UserDict) -> None:
      # ...
  

mypy設定と実行

• 設定ファイル: mypyの設定はpyproject.toml内の[tool.mypy]セクションで管理されています。
• 実行方法: 開発中は、以下のコマンドでいつでも型チェックを実行できます。

  uv run mypy tree_sitter_analyzer/
  

• エラーへの対処: mypyエラーが検出された場合は、コードを修正してエラーを解消してください。意図的な型違反（例: 動的なプラグイン読み込みなど）でエラーを無視する必要がある場合は、# type: ignore[error-code]コメントを使用し、その理由を簡潔に説明してください。

5. テスト

• テストの実行: プロジェクト全体のテストは、プロジェクト環境と5分以内の実行契約を使うため uv run pytest -q で実行します。

  uv run pytest -q
  

  開発中の反復確認は、重い全言語/高速化しきれない suite を外すと体感が安定します。

  PYTEST_XDIST_AUTO_NUM_WORKERS=2 uv run pytest -q -m "not slow and not full_language"
  PYTEST_XDIST_AUTO_NUM_WORKERS=1 uv run pytest -q --maxfail=1 -m "not slow and not full_language"
  

• カバレッジ: コードの変更には、可能な限り高いテストカバレッジを維持することが求められます。

---

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