# スコープ定義書（Scope Statement）

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

---

## 1. プロジェクトスコープ記述

Tree-sitter Analyzerは、AI時代に最適化されたエンタープライズグレードのコード解析ツールであり、開発者とAIアシスタントが大規模コードベースを効率的に理解・操作できるようにする。

## 2. プロダクトスコープ

### 2.1 主要機能グループ

#### 機能グループ1: コア解析エンジン
**目的:** 多言語コードの構造解析と要素抽出

**含まれる機能:**
- ✅ 構文解析（tree-sitterベース）
- ✅ コード要素抽出（クラス、関数、メソッド等）
- ✅ 階層構造分析
- ✅ 複雑度計算（Cyclomatic Complexity）
- ✅ 行範囲特定

**非機能要件:**
- パフォーマンス: 10,000行のファイルを1秒以内に解析
- 精度: 構文解析エラー率 < 0.1%
- メモリ効率: 100MBファイルの解析で500MB以内のメモリ使用

#### 機能グループ2: 言語サポート
**目的:** 多様なプログラミング言語への対応

**現在実装済み:** 7言語（Java, Python, JavaScript, TypeScript, HTML, CSS, Markdown）

**サポート言語:**

| 言語 | サポートレベル | プラグイン実装 | 主要機能 |
|------|---------------|---------------|---------|
| Java | 完全 | ✅ | Spring、JPA、エンタープライズ機能 |
| Python | 完全 | ✅ | 型アノテーション、デコレータ、モダン構文 |
| JavaScript | 完全 | ✅ | ES6+、React/Vue/Angular、JSX |
| TypeScript | 完全 | ✅ | インターフェース、型システム、TSX |
| HTML | 完全 | ✅ | DOM構造、要素分類、属性解析 |
| CSS | 完全 | ✅ | セレクタ、プロパティ分類、詳細度計算 |
| Markdown | 完全 | ✅ | 見出し、コードブロック、リンク、表 |

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

**拡張性:**
- プラグインアーキテクチャによる新言語追加
- 標準インターフェース（LanguagePlugin）の提供

#### 機能グループ3: AI統合（MCP）
**目的:** AIアシスタントとのシームレスな連携

**含まれる機能:**
- ✅ MCPサーバー実装
- ✅ 標準MCPツールセット
  - `check_code_scale`: コード規模確認
  - `analyze_code_structure`: 構造解析
  - `extract_code_section`: コード抽出
  - `list_files`: ファイル一覧
  - `search_content`: コンテンツ検索
  - `find_and_grep`: 複合検索
- ✅ トークン制限対応（SMART要約）
- ✅ 非同期処理サポート

**統合対象:**
- Claude Desktop
- Cursor
- Roo Code
- その他MCPクライアント

#### 機能グループ4: CLIツール
**目的:** コマンドラインでの直接実行

**含まれるコマンド:**
- `tree-sitter-analyzer`: メイン解析コマンド
- `list-files`: ファイル検索
- `search-content`: コンテンツ検索
- `find-and-grep`: 複合検索

**オプション体系:**
- 出力形式: JSON、YAML、テキスト
- フィルタリング: 言語、拡張子、パス
- 出力制御: 詳細度、要約モード
- ファイル出力: 結果の永続化

#### 機能グループ5: 検索機能
**目的:** 高速かつ正確なファイル・コンテンツ検索

**ファイル検索（fd統合）:**
- ✅ 高速ファイル検出
- ✅ パターンマッチング（glob、正規表現）
- ✅ プロジェクト境界保護
- ✅ .gitignore尊重

**コンテンツ検索（ripgrep統合）:**
- ✅ 高速全文検索
- ✅ 正規表現サポート
- ✅ ファイルタイプフィルタ
- ✅ コンテキスト表示

**複合検索:**
- ✅ 2段階検索（ファイル→コンテンツ）
- ✅ インテリジェントフィルタリング

#### 機能グループ6: セキュリティ
**目的:** 安全なファイルアクセスの保証

**含まれる機能:**
- ✅ パストラバーサル防止
- ✅ プロジェクトルート検証
- ✅ シンボリックリンク検証
- ✅ 相対パス正規化
- ✅ アクセス権限チェック

**セキュリティ基準:**
- CWE-22対策（パストラバーサル）
- OWASP推奨事項準拠
- 定期的なセキュリティ監査

#### 機能グループ7: パフォーマンス最適化
**目的:** 大規模コードベースの高速処理

**含まれる機能:**
- ✅ キャッシュシステム
  - ファイル単位のキャッシュ
  - タイムスタンプベースの無効化
  - LRUキャッシュ戦略
- ✅ 非同期処理
  - 並行ファイル解析
  - 非ブロッキングI/O
- ✅ メモリ管理
  - ストリーミング処理
  - 段階的な結果生成

**パフォーマンス目標:**
- 中規模プロジェクト（1,000ファイル）: < 10秒
- 大規模プロジェクト（10,000ファイル）: < 60秒
- メモリ使用量: プロジェクトサイズの5倍以内

### 2.2 ユーザーグループ

| ユーザーグループ | ニーズ | 提供価値 |
|----------------|-------|---------|
| **AIツールユーザー** | AIとの対話でコード理解 | MCP統合、SMART要約 |
| **CLI開発者** | スクリプト統合、自動化 | CLIツール、JSON出力 |
| **個人開発者** | コードベース把握 | 高速解析、可視化 |
| **開発チーム** | コードレビュー支援 | 構造分析、品質指標 |
| **OSS貢献者** | 新機能追加、言語拡張 | プラグイン機構、API |

## 3. プロジェクト境界

### 3.1 含まれるもの（In-Scope）

#### 技術範囲
1. **静的コード解析**
   - 構文解析
   - 構造分析
   - メトリクス計算

2. **AI統合**
   - MCPプロトコル実装
   - トークン最適化
   - 自然言語インターフェース

3. **検索機能**
   - ファイル検索
   - コンテンツ検索
   - 複合検索

4. **CLI & API**
   - コマンドラインツール
   - プログラマティックAPI
   - プラグインシステム

#### 運用範囲
- ローカル実行環境
- Python 3.10+プラットフォーム
- Windows/macOS/Linux対応

### 3.2 含まれないもの（Out-of-Scope）

#### 除外機能
1. **動的解析**
   - ❌ コード実行
   - ❌ ランタイム分析
   - ❌ デバッグ機能

2. **IDE統合**
   - ❌ VS Code拡張
   - ❌ IntelliJ プラグイン
   - ❌ リアルタイム編集支援

3. **コード変更機能**
   - ❌ 自動リファクタリング
   - ❌ コード生成
   - ❌ 自動修正

4. **クラウド機能**
   - ❌ クラウドストレージ
   - ❌ マルチユーザー協業
   - ❌ オンライン実行

5. **ビルド・実行**
   - ❌ コンパイラ統合
   - ❌ ビルドシステム
   - ❌ テスト実行ランナー

### 3.3 境界条件

#### 技術的境界
- **言語サポート:** tree-sitterで対応可能な言語のみ（現在7言語実装済み）
- **ファイルサイズ:** 実用的範囲（推奨: < 100MB/ファイル）
- **プロジェクト規模:** 推奨 < 100,000ファイル

#### 依存性境界
- **必須依存:**
  - Python 3.10+
  - tree-sitterライブラリ
  - 各言語のtree-sitterパーサー

- **オプション依存:**
  - fd（ファイル検索高速化）
  - ripgrep（コンテンツ検索高速化）
  - MCP関連ライブラリ（AI統合時）

## 4. 成果物定義

### 4.1 主要成果物

| 成果物 | 説明 | 責任者 | 完成基準 |
|--------|------|--------|---------|
| **Pythonパッケージ** | PyPI配布可能なwheel | 開発チーム | pip installable、全テスト合格 |
| **MCPサーバー** | AI統合用サーバー | 開発チーム | MCPクライアントで動作確認 |
| **CLIツール** | コマンドラインツール | 開発チーム | 全コマンド動作、ヘルプ完備 |
| **ドキュメント** | ユーザー・開発者向け | 全メンバー | 主要機能カバー、例示充実 |
| **テストスイート** | 自動テスト群 | QAチーム | カバレッジ > 80%、全合格 |

### 4.2 ドキュメント成果物

| ドキュメント | 目的 | 対象読者 |
|-------------|------|---------|
| README | プロジェクト概要、クイックスタート | 全ユーザー |
| API仕様 | プログラマティックAPI | 開発者 |
| CLIリファレンス | コマンドライン使用法 | CLIユーザー |
| MCP統合ガイド | AI統合手順 | AIツールユーザー |
| 開発者ガイド | 貢献方法、アーキテクチャ | 貢献者 |
| テスト仕様 | テスト戦略、ケース | QAチーム |

## 5. 承認基準

### 5.1 機能受入基準

各機能グループは以下の基準を満たす必要がある：

1. **機能完全性:** 仕様通りの動作
2. **テストカバレッジ:** > 80%
3. **パフォーマンス:** 定義された目標達成
4. **ドキュメント:** 使用方法の記載
5. **互換性:** 3プラットフォーム動作確認

### 5.2 リリース基準

| 基準 | 要件 | 検証方法 |
|------|------|---------|
| 機能完成度 | スコープ内機能100%実装 | 機能テスト |
| 品質 | 全テスト合格 | CI/CD |
| 互換性 | 3OS動作確認 | プラットフォームテスト |
| ドキュメント | 主要機能説明完備 | レビュー |
| セキュリティ | 既知脆弱性なし | セキュリティスキャン |

## 6. スコープ変更管理

### 6.1 変更プロセス
1. **変更要求:** Issue/PR作成
2. **影響分析:** スコープ・スケジュール・品質への影響評価
3. **承認:** プロジェクトオーナー承認
4. **実装:** 変更実施
5. **文書更新:** スコープ定義書更新

### 6.2 変更承認権限
- **軽微な変更:** コア開発者
- **中程度の変更:** プロジェクトマネージャー
- **重大な変更:** プロジェクトオーナー

## 7. 除外事項の明確化

以下は明示的にプロジェクトスコープから除外される：

### 7.1 技術的除外
- コード実行エンジン
- リアルタイム協業機能
- グラフィカルUIツール
- IDE統合プラグイン
- クラウドサービス基盤

### 7.2 運用的除外
- 24/7サポート
- SLA保証
- マネージドサービス
- エンタープライズライセンス
- 有償トレーニング

---

## 改訂履歴

| バージョン | 日付 | 変更内容 | 承認者 |
|-----------|------|---------|--------|
| 1.0 | 2025-11-02 | 初版作成 | aisheng.yu |
| 1.1 | 2025-11-03 | 実装実績との整合性確保<br>- 言語サポート表: C/C++、Rust、Go を削除（プラグイン未実装）<br>- 言語サポート表: 「プラグイン実装」列を追加（全7言語✅）<br>- 注記追加: 未実装言語の説明とプラグイン追加方法<br>- 機能グループ2: 実装済み言語数を明記（7言語）<br>- 技術的境界: 現在の実装状況を反映 | aisheng.yu |
