# アーキテクチャ設計

**文書番号:** SPEC-002  
**バージョン:** 1.0  
**作成日:** 2025-11-03  
**最終更新:** 2025-11-03

---

## 1. 概要

本文書は、Tree-sitter Analyzerの詳細なアーキテクチャ設計を記述する。システム全体の構造、コンポーネント間の関係、データフロー、および技術的な設計決定を明確化する。

---

## 2. アーキテクチャ全体図

```
┌─────────────────────────────────────────────────────────────┐
│                     ユーザーインターフェース層                   │
├──────────────────────┬──────────────────────────────────────┤
│   CLI Interface      │   MCP Server Interface               │
│   (argparse)         │   (stdio/websocket)                  │
└──────────────────────┴──────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                     サービス層（Business Logic）               │
├─────────────────┬───────────────────┬───────────────────────┤
│ API Facade      │ AnalysisEngine    │ QueryService          │
│ - analyze_file()│ - analyze_file()  │ - execute_query()     │
│ - analyze_code()│ - batch_analyze() │ - filter_results()    │
└─────────────────┴───────────────────┴───────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                     コア解析エンジン層                          │
├──────────────────────┬──────────────────────────────────────┤
│   Parser             │   PluginManager                      │
│   - parse_file()     │   - get_plugin()                     │
│   - parse_code()     │   - register_plugin()                │
└──────────────────────┴──────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                     言語プラグイン層                            │
├────────┬────────┬────────┬────────┬────────┬────────────────┤
│ Python │ Java   │ JS/TS  │ HTML   │ CSS    │ Markdown       │
│ Plugin │ Plugin │ Plugin │ Plugin │ Plugin │ Plugin         │
│  ✅    │  ✅    │  ✅    │  ✅    │  ✅    │  ✅           │
└────────┴────────┴────────┴────────┴────────┴────────────────┘
                    ※ 実装済み: 7言語のみ
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                     データ管理層                               │
├──────────────────────┬──────────────────────────────────────┤
│   CacheService       │   OutputManager                      │
│   - 3-tier cache     │   - format output                    │
│   - L1/L2/L3         │   - console/file output              │
└──────────────────────┴──────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                     基盤層                                     │
├──────────────────────┬──────────────────────────────────────┤
│   Tree-sitter        │   Python Runtime                     │
│   - C bindings       │   - asyncio                          │
│   - Language parsers │   - typing system                    │
└──────────────────────┴──────────────────────────────────────┘
```

---

## 3. コンポーネント詳細設計

### 3.1 ユーザーインターフェース層

#### 3.1.1 CLI Interface
**責務:**
- コマンドライン引数の解析
- ユーザー入力の検証
- 結果の整形表示

**主要クラス:**
```python
class CLICommandFactory:
    """CLI コマンド生成のファクトリークラス"""
    
    @staticmethod
    def create_command(args: argparse.Namespace) -> Any:
        """引数に基づいて適切なコマンドを生成"""
        pass

class DefaultCommand:
    """デフォルトの解析コマンド"""
    
    def execute(self) -> int:
        """コマンド実行"""
        pass
```

**設計決定:**
- ✅ argparseを使用（標準ライブラリ、依存なし）
- ✅ コマンドパターン（DefaultCommand, QueryCommand等）
- ✅ 豊富なヘルプメッセージ

---

#### 3.1.2 MCP Server Interface
**責務:**
- MCPプロトコル実装（stdio/websocket）
- AI統合（Claude, Cursor等）
- リアルタイム解析応答

**主要クラス:**
```python
class TreeSitterAnalyzerMCPServer:
    """MCPサーバーのメインクラス"""
    
    def __init__(self, project_root: str | None = None):
        self.server: Server | None = None
        self._initialization_complete = False
        
        # MCP Tools - 8ツール（公開版）
        self.query_tool = QueryTool(project_root)
        self.read_partial_tool = ReadPartialTool(project_root)
        self.table_format_tool = TableFormatTool(project_root)
        self.analyze_scale_tool = AnalyzeScaleTool(project_root)
        self.list_files_tool = ListFilesTool(project_root)
        self.search_content_tool = SearchContentTool(project_root)
        self.find_and_grep_tool = FindAndGrepTool(project_root)
        
        # 9ツール目（テスト版）: UniversalAnalyzeTool（オプション）
        # self.universal_analyze_tool = UniversalAnalyzeTool(project_root)
    
    def create_server(self) -> Server:
        """MCPサーバーの生成と設定（8ツール登録）"""
        pass
    
    async def run(self):
        """サーバー起動"""
        pass
```

**設計決定:**
- ✅ 非同期I/O（asyncio）
- ✅ stdioトランスポート（stdio_server）
- ✅ API facadeを通じた統一的なアクセス
- ✅ ツールベースアーキテクチャ（8ツール: query_code, extract_code_section, analyze_code_structure, check_code_scale, analyze_file, list_files, search_content, find_and_grep）
- ✅ プロジェクトルート境界管理（SecurityValidator連携）

---

### 3.2 サービス層

#### 3.2.1 API Facade
**責務:**
- 統一的な公開インターフェース
- CLIとMCPの共通エントリーポイント
- バージョン管理と互換性の確保

**クラス図:**
```python
# api.py
def analyze_file(
    file_path: str | Path,
    language: str | None = None,
    queries: list[str] | None = None,
    include_elements: bool = True,
    include_queries: bool = True,
) -> dict[str, Any]:
    """
    ファイル解析のメイン関数
    
    Args:
        file_path: 解析するファイルのパス
        language: プログラミング言語（自動検出可能）
        queries: 実行するクエリのリスト
        include_elements: 要素抽出を含めるか
        include_queries: クエリを実行するか
    
    Returns:
        解析結果の辞書
    """
    engine = get_engine()
    analysis_result = engine.analyze_file(file_path, language)
    return format_result(analysis_result)

def analyze_code(
    source_code: str,
    language: str,
    queries: list[str] | None = None,
    include_elements: bool = True,
    include_queries: bool = True,
) -> dict[str, Any]:
    """コード文字列を直接解析"""
    engine = get_engine()
    analysis_result = engine.analyze_code(source_code, language)
    return format_result(analysis_result)
```

**設計決定:**
- ✅ シンプルな関数ベースAPI
- ✅ シングルトンパターンでエンジン管理
- ✅ CLIとMCPの統一インターフェース

---

#### 3.2.2 AnalysisEngine
**責務:**
- 解析処理のオーケストレーション
- プラグイン管理との連携
- キャッシュサービスの活用

**クラス図:**
```python
# 実際の実装は tree_sitter_analyzer/core/engine.py
class AnalysisEngine:
    """解析エンジンのメインクラス"""
    
    def __init__(self) -> None:
        """Initialize the AnalysisEngine with core components."""
        self.parser = Parser()
        self.query_executor = QueryExecutor()
        self.language_detector = LanguageDetector()
        
        # プラグインシステム初期化
        self.plugin_manager = PluginManager()
        self._initialize_plugins()
        
        logger.info("AnalysisEngine initialized successfully")
    
    def analyze_file(
        self,
        file_path: str | Path,
        language: str | None = None
    ) -> AnalysisResult:
        """単一ファイル解析"""
        file_path_obj = Path(file_path)
        
        # 1. ファイル存在チェック
        if not file_path_obj.exists():
            raise FileNotFoundError(f"File not found: {file_path}")
        
        # 2. 言語判定
        detected_language = self._determine_language(file_path_obj, language)
        
        # 3. ファイルパース
        parse_result = self.parser.parse_file(str(file_path), detected_language)
        
        if not parse_result.success:
            return self._create_empty_result(
                str(file_path), detected_language, error=parse_result.error_message
            )
        
        # 4. 解析実行
        return self._perform_analysis(parse_result)
    
    def analyze_code(
        self,
        source_code: str,
        language: str
    ) -> AnalysisResult:
        """コード文字列解析"""
        plugin = self.plugin_manager.get_plugin(language)
        result = plugin.analyze_code(source_code)
        return result
```

**設計決定:**
- ✅ プラグインベースアーキテクチャ
- ✅ Parser + QueryExecutor + PluginManager の協調動作
- ✅ LanguageDetector による言語自動検出
- ✅ エラー耐性（パース失敗時の空結果返却）

---

#### 3.2.3 QueryService
**責務:**
- Tree-sitterクエリの実行
- クエリ結果のフィルタリング
- カスタムクエリのサポート

**設計決定:**
- ✅ 定義済みクエリのライブラリ
- ✅ カスタムクエリのサポート
- ✅ クエリ結果の後処理

---

### 3.3 コア解析エンジン層

#### 3.3.1 Parser
**責務:**
- Tree-sitterライブラリとの統合
- AST生成
- ファイル/コードのパース

**主要メソッド:**
```python
class Parser:
    """Tree-sitterパーサーのラッパー"""
    
    def __init__(self):
        self.language_loader = LanguageLoader()
    
    def parse_file(self, file_path: str, language: str) -> Tree:
        """ファイルを解析してAST生成"""
        # 1. 言語のパーサーを取得
        parser = self.language_loader.get_parser(language)
        
        # 2. ファイル読み込み
        with open(file_path, 'rb') as f:
            source_code = f.read()
        
        # 3. パース実行
        tree = parser.parse(source_code)
        
        return tree
    
    def parse_code(self, source_code: bytes, language: str) -> Tree:
        """コードを解析してAST生成"""
        parser = self.language_loader.get_parser(language)
        tree = parser.parse(source_code)
        return tree
```

**設計決定:**
- ✅ 言語検出の自動化（拡張子ベース）
- ✅ エラーハンドリング（構文エラー対応）
- ✅ エンコーディング検出機能

---

#### 3.3.2 PluginManager
**責務:**
- 言語プラグインの管理
- プラグインの登録と取得
- 動的プラグインロード

**実装:**
```python
# 実際の実装は tree_sitter_analyzer/plugins/manager.py
class PluginManager:
    """プラグイン管理クラス - 動的プラグイン検出システム"""
    
    def __init__(self) -> None:
        """Initialize the plugin manager."""
        self._loaded_plugins: dict[str, LanguagePlugin] = {}
        self._plugin_classes: dict[str, type[LanguagePlugin]] = {}
        self._entry_point_group = "tree_sitter_analyzer.plugins"
    
    def load_plugins(self) -> list[LanguagePlugin]:
        """
        エントリーポイントとローカルディレクトリから全プラグインをロード
        
        Returns:
            正常にロードされたプラグインインスタンスのリスト
        """
        loaded_plugins = []
        
        # エントリーポイントからロード（インストール済みパッケージ）
        entry_point_plugins = self._load_from_entry_points()
        loaded_plugins.extend(entry_point_plugins)
        
        # ローカルlanguagesディレクトリからロード
        local_plugins = self._load_from_local_directory()
        loaded_plugins.extend(local_plugins)
        
        return loaded_plugins
    
    def get_plugin(self, language: str) -> LanguagePlugin | None:
        """言語に対応するプラグインを取得"""
        return self._loaded_plugins.get(language.lower())
```

**設計決定:**
- ✅ 動的プラグイン検出（エントリーポイント + ローカルディレクトリ）
- ✅ 辞書ベースの高速ルックアップ
- ✅ 重複プラグインの自動除外
- ✅ 外部パッケージプラグインのサポート（setuptools entry_points）

---

### 3.4 言語プラグイン層

#### 3.4.1 言語プラグインアーキテクチャ

**プラグインインターフェース:**
```python
class LanguagePlugin(ABC):
    """言語プラグインの基底クラス"""
    
    @property
    @abstractmethod
    def name(self) -> str:
        """言語名"""
        pass
    
    @property
    @abstractmethod
    def file_extensions(self) -> list[str]:
        """対応する拡張子"""
        pass
    
    @abstractmethod
    async def analyze_file(
        self,
        file_path: str,
        request: AnalysisRequest
    ) -> AnalysisResult:
        """ファイル解析"""
        pass
    
    @abstractmethod
    async def analyze_code(
        self,
        source_code: str,
        request: AnalysisRequest
    ) -> AnalysisResult:
        """コード解析"""
        pass
```

**ElementExtractor基底クラス:**
```python
class ElementExtractor(ABC):
    """要素抽出の基底クラス"""
    
    @abstractmethod
    def extract_functions(
        self,
        tree: Tree,
        source_code: str
    ) -> list[Function]:
        """関数定義を抽出"""
        pass
    
    @abstractmethod
    def extract_classes(
        self,
        tree: Tree,
        source_code: str
    ) -> list[Class]:
        """クラス定義を抽出"""
        pass
    
    @abstractmethod
    def extract_variables(
        self,
        tree: Tree,
        source_code: str
    ) -> list[Variable]:
        """変数宣言を抽出"""
        pass
    
    @abstractmethod
    def extract_imports(
        self,
        tree: Tree,
        source_code: str
    ) -> list[Import]:
        """インポート文を抽出"""
        pass
```

**Pythonプラグイン実装例:**
```python
class PythonPlugin(LanguagePlugin):
    """Pythonプラグイン"""
    
    @property
    def name(self) -> str:
        return "python"
    
    @property
    def file_extensions(self) -> list[str]:
        return [".py", ".pyi"]
    
    async def analyze_file(
        self,
        file_path: str,
        request: AnalysisRequest
    ) -> AnalysisResult:
        """Pythonファイルの解析"""
        # パース実行
        tree = self.parser.parse_file(file_path)
        
        # 要素抽出
        extractor = PythonElementExtractor()
        elements = extractor.extract_all_elements(tree, source_code)
        
        # 結果構築
        return AnalysisResult(
            success=True,
            language="python",
            elements=elements,
            node_count=tree.root_node.named_child_count,
            line_count=len(source_code.split('\n'))
        )
```

**設計決定:**
- ✅ プラグインベースアーキテクチャ（拡張性）
- ✅ 統一インターフェース（ElementExtractor）
- ✅ 言語固有の最適化可能

---

#### 3.4.2 サポート言語一覧

| 言語 | プラグインクラス | tree-sitterライブラリ | プラグイン実装 | 状態 |
|------|----------------|---------------------|--------------|------|
| Python | `PythonPlugin` | `tree-sitter-python` | ✅ | ✅ 完全対応 |
| Java | `JavaPlugin` | `tree-sitter-java` | ✅ | ✅ 完全対応 |
| JavaScript | `JavaScriptPlugin` | `tree-sitter-javascript` | ✅ | ✅ 完全対応 |
| TypeScript | `TypeScriptPlugin` | `tree-sitter-typescript` | ✅ | ✅ 完全対応 |
| HTML | `HtmlPlugin` | `tree-sitter-html` | ✅ | ✅ 完全対応 |
| CSS | `CssPlugin` | `tree-sitter-css` | ✅ | ✅ 完全対応 |
| Markdown | `MarkdownPlugin` | `tree-sitter-markdown` | ✅ | ✅ 完全対応 |

**注:** 
- 上記7言語のみプラグイン実装完了（`tree_sitter_analyzer/languages/`に実ファイル存在）
- C、C++、Go、Rust、JSON等は`LanguageDetector`に定義済みだが、プラグイン未実装（パース不可）
- 新言語追加はプラグインクラスの作成が必要

---

### 3.5 データ管理層

#### 3.5.1 CacheService
**責務:**
- 解析結果のキャッシング
- 3層階層キャッシュ（L1/L2/L3）
- メモリ効率的なキャッシュポリシー

**実装:**
```python
class CacheService:
    """キャッシュ管理サービス"""
    
    def __init__(
        self,
        l1_maxsize: int = 100,
        l2_maxsize: int = 1000,
        l3_maxsize: int = 10000,
        ttl_seconds: int = 3600
    ):
        # 3層キャッシュ構造
        self._l1_cache = LRUCache(maxsize=l1_maxsize)  # 高速アクセス
        self._l2_cache = TTLCache(maxsize=l2_maxsize, ttl=ttl_seconds)  # 中期保存
        self._l3_cache = LRUCache(maxsize=l3_maxsize)  # 長期保存
        self._lock = threading.RLock()
        self._stats = {"hits": 0, "misses": 0}
    
    def get(self, key: str) -> Any | None:
        """キャッシュ取得（L1→L2→L3の順で検索）"""
        with self._lock:
            # L1チェック
            if key in self._l1_cache:
                self._stats["hits"] += 1
                return self._l1_cache[key].value
            
            # L2チェック
            if key in self._l2_cache:
                entry = self._l2_cache[key]
                # L1に昇格
                self._l1_cache[key] = entry
                self._stats["hits"] += 1
                return entry.value
            
            # L3チェック
            if key in self._l3_cache:
                entry = self._l3_cache[key]
                # L2に昇格
                self._l2_cache[key] = entry
                self._stats["hits"] += 1
                return entry.value
            
            self._stats["misses"] += 1
            return None
    
    def set(self, key: str, value: Any, ttl: int | None = None):
        """キャッシュ保存"""
        with self._lock:
            expires_at = None
            if ttl:
                expires_at = datetime.now() + timedelta(seconds=ttl)
            
            entry = CacheEntry(
                value=value,
                created_at=datetime.now(),
                expires_at=expires_at
            )
            
            # L1に保存
            self._l1_cache[key] = entry
```

**設計決定:**
- ✅ 3層階層キャッシュ（L1/L2/L3）
- ✅ LRUとTTLの組み合わせ
- ✅ スレッドセーフ実装

---

#### 3.5.2 OutputManager
**責務:**
- 解析結果の出力
- コンソール/ファイル出力
- フォーマット管理

**実装:**
```python
class OutputManager:
    """出力管理クラス"""
    
    @staticmethod
    def output_result(data: Any, format: str = "json") -> None:
        """結果を出力"""
        if format == "json":
            print(json.dumps(data, indent=2, ensure_ascii=False))
        elif format == "table":
            # テーブル形式で出力
            print_table(data)
        else:
            print(str(data))
    
    @staticmethod
    def output_to_file(
        data: Any,
        output_path: str,
        format: str = "json"
    ) -> None:
        """ファイルに出力"""
        with open(output_path, 'w', encoding='utf-8') as f:
            if format == "json":
                json.dump(data, f, indent=2, ensure_ascii=False)
            else:
                f.write(str(data))
```

**設計決定:**
- ✅ シンプルな静的メソッド
- ✅ JSON/テーブル/プレーンテキスト対応
- ✅ ファイル出力サポート

---

## 4. データフロー

### 4.1 単一ファイル解析のフロー

```
[ユーザー] 
    ↓ (1) tree-sitter-analyzer analyze file.py
[CLI/MCPインターフェース]
    ↓ (2) api.analyze_file()
[API Facade]
    ↓ (3) get_engine().analyze_file()
[AnalysisEngine]
    ↓ (4) plugin_manager.get_plugin()
[PythonPlugin]
    ↓ (5) parser.parse_file() + extractor.extract_all_elements()
[AnalysisResult]
    ↓ (6) format_result()
[OutputManager]
    ↓ (7) 結果出力
[ユーザー]
```

---

### 4.2 MCP非同期解析のフロー

```
[AI Tool (Claude)]
    ↓ (1) MCP Request (analyze_file)
[TreeSitterAnalyzerMCPServer]
    ↓ (2) handle_tool_call()
[API Facade]
    ↓ (3) api.analyze_file()
[AnalysisEngine]
    ↓ (4) plugin_manager.get_plugin()
[LanguagePlugin]
    ↓ (5) 非同期解析実行
[AnalysisResult]
    ↓ (6) JSON形式で返却
[TreeSitterAnalyzerMCPServer]
    ↓ (7) MCP Response
[AI Tool]
    ← (8) 結果受信
```

---

## 5. 非機能要件の実装

### 5.1 パフォーマンス

**目標:**
- 単一ファイル解析: < 100ms (小規模ファイル < 1000行)
- 中規模ファイル解析: < 500ms (1000-10000行)
- キャッシュヒット時: < 10ms

**実装:**
- ✅ 3層キャッシュ（L1/L2/L3）
- ✅ 非同期処理（asyncio）
- ✅ 遅延評価（詳細情報のオプショナル化）
- ✅ PerformanceMonitor による計測

---

### 5.2 スケーラビリティ

**目標:**
- 100,000+ 行のファイル対応
- 1,000+ ファイルのプロジェクト解析

**実装:**
- ✅ メモリ効率的なAST処理
- ✅ ストリーミング処理（必要に応じて）
- ✅ プログレス表示機能

---

### 5.3 セキュリティ

**目標:**
- パストラバーサル防止
- 安全なファイルアクセス
- 悪意あるコードの解析時の安全性

**実装:**
- ✅ SecurityValidator によるパス検証
- ✅ ProjectBoundaryManager によるプロジェクト境界管理
- ✅ タイムアウト機能
- ✅ サンドボックス化された解析環境

---

### 5.4 信頼性

**目標:**
- エラー時の適切なハンドリング
- 部分的な失敗の許容
- 構文エラーがあっても解析継続

**実装:**
- ✅ 例外の詳細なログ（utils.log_error）
- ✅ Tree-sitterのエラー耐性活用
- ✅ 個別エラーハンドリング
- ✅ AnalysisResult.success フラグ

---

## 6. 技術的な設計決定

### 6.1 言語選択: Python

**理由:**
- ✅ Tree-sitterの公式バインディング
- ✅ 豊富なエコシステム
- ✅ AI統合が容易（MCP）
- ✅ 開発速度と保守性

**トレードオフ:**
- ⚠️ パフォーマンス（C/Rustより遅い）
  - 緩和策: CacheService、プラグイン最適化
- ⚠️ 型安全性
  - 緩和策: mypy、厳格な型ヒント（全ファイルで型チェック済み）

---

### 6.2 Tree-sitter採用

**理由:**
- ✅ 高速なパース（エラー耐性あり）
- ✅ 多言語対応（40+言語）
- ✅ インクリメンタルパース対応
- ✅ 構文エラーがあっても部分的にパース可能

**トレードオフ:**
- ⚠️ 言語サポートの品質にばらつき
  - 緩和策: 主要8言語に注力、プラグインで拡張

---

### 6.3 プラグインアーキテクチャ

**理由:**
- ✅ 言語ごとの特性に対応
- ✅ 新言語追加が容易
- ✅ 保守性と拡張性の向上

**実装:**
- PluginManager による動的プラグイン管理
- ElementExtractor による統一的な要素抽出インターフェース
- 言語固有の最適化が可能

---

### 6.4 3層キャッシュ戦略

**理由:**
- ✅ 解析の高速化（10-100倍）
- ✅ メモリ効率的な階層構造（L1/L2/L3）
- ✅ TTLとLRUの組み合わせ

**トレードオフ:**
- ⚠️ メモリ使用量の増加
  - 緩和策: 設定可能なキャッシュサイズ、LRUポリシー
- ⚠️ キャッシュ一貫性の管理
  - 緩和策: TTLによる自動期限切れ

---

### 6.5 API Facade パターン

**理由:**
- ✅ CLIとMCPの統一インターフェース
- ✅ 内部実装の変更からクライアントを保護
- ✅ バージョン管理と後方互換性

**実装:**
- api.pyによる単一エントリーポイント
- シンプルな関数ベースAPI
- シングルトンパターンでエンジン管理

---

## 7. 拡張性

### 7.1 新言語追加

**手順:**
1. `LanguagePlugin`を継承したクラス作成
2. tree-sitterライブラリのインストール
3. クエリの定義（言語固有）
4. テストケースの作成
5. ドキュメント更新

**例: Rubyサポート追加**
```python
class RubyPlugin(LanguagePlugin):
    @property
    def name(self) -> str:
        return "Ruby"
    
    @property
    def file_extensions(self) -> List[str]:
        return [".rb"]
    
    def get_parser(self) -> Parser:
        import tree_sitter_ruby
        parser = Parser()
        parser.set_language(tree_sitter_ruby.language())
        return parser
```

---

### 7.2 新MCPツール追加

**手順:**
1. `TreeSitterAnalyzerMCPServer`の`create_server()`メソッドを更新
2. 新しいツールの定義（`Tool`オブジェクト作成）
3. ツールハンドラーの実装（`@server.call_tool()`デコレータ）
4. API facadeに新しい関数を追加（必要に応じて）
5. テスト作成

---

### 7.3 新出力フォーマット追加

**手順:**
1. `OutputManager`に新しい出力メソッドを追加
2. フォーマッターの実装
3. テスト作成

**例: Markdown出力**
```python
class OutputManager:
    @staticmethod
    def output_markdown(data: dict[str, Any]) -> str:
        """Markdown形式で出力"""
        md = f"# Analysis Result\n\n"
        md += f"- Language: {data['language']}\n"
        md += f"- Lines: {data['line_count']}\n"
        return md
```

---

## 8. 依存関係管理

### 8.1 主要依存ライブラリ

| ライブラリ | バージョン | 目的 | ライセンス |
|-----------|----------|------|----------|
| tree-sitter | ^0.20.0 | コアパーサー | MIT |
| tree-sitter-python | ^0.20.0 | Pythonサポート | MIT |
| tree-sitter-java | ^0.20.0 | Javaサポート | MIT |
| mcp | ^1.0.0 | MCPプロトコル | MIT |
| asyncio | (標準) | 非同期I/O | PSF |
| pytest | ^7.0.0 | テスト | MIT |
| mypy | ^1.0.0 | 型チェック | MIT |

---

### 8.2 依存関係の原則

- ✅ 最小限の依存
- ✅ 標準ライブラリ優先
- ✅ アクティブに保守されているライブラリのみ
- ✅ ライセンス互換性の確認

---

## 9. テスタビリティ

### 9.1 ユニットテスト

**戦略:**
- すべてのパブリックAPIにテスト
- モック/スタブの活用
- エッジケースのカバー
- pytest + pytest-asyncio + pytest-mock使用

**例:**
```python
def test_api_analyze_file(tmp_path):
    # Arrange
    test_file = tmp_path / "test.py"
    test_file.write_text("def hello(): pass")
    
    # Act
    result = api.analyze_file(str(test_file), language="python")
    
    # Assert
    assert result["success"] is True
    assert result["language_info"]["language"] == "python"
    assert len(result["elements"]) > 0
```

---

### 9.2 統合テスト

**戦略:**
- 実際のファイルでテスト
- E2Eシナリオ
- パフォーマンステスト

---

### 9.3 回帰テスト

**戦略:**
- ゴールデンファイルとの比較
- 既知のバグの再現テスト

---

## 10. デプロイメント

### 10.1 配布形式

- **PyPI:** `pip install tree-sitter-analyzer`
- **GitHub Releases:** バイナリ配布（将来）
- **Docker:** コンテナイメージ（将来）

---

### 10.2 バージョニング

**セマンティックバージョニング:**
- **MAJOR**: 破壊的変更
- **MINOR**: 新機能追加
- **PATCH**: バグ修正

---

## 11. 改訂履歴

| バージョン | 日付 | 変更内容 | 承認者 |
|-----------|------|---------|--------|
| 1.0 | 2025-11-03 | 初版作成 | aisheng.yu |
| 1.1 | 2025-11-03 | 実装との整合性を確保する修正<br>- 言語サポート表: 8言語→7言語に修正（C++削除）<br>- プラグイン実装状況列を追加<br>- PluginManager: 動的検出システムの実装詳細を反映<br>- AnalysisEngine: 実装コード構造に合わせた修正<br>- MCPツール: 8ツールの明示（公開版）<br>- 注記追加: 未実装言語の明記 | aisheng.yu |

---

**最終更新:** 2025-11-03  
**管理者:** aisheng.yu  
**連絡先:** aimasteracc@gmail.com
