tree-sitter-analyzer 0.9.4__tar.gz → 0.9.6__tar.gz

tree_sitter_analyzer-0.9.6/.kiro/steering/product.md

@@ -0,0 +1,32 @@
+# Product Overview
+
+## What is Tree-sitter Analyzer?
+
+Tree-sitter Analyzer is a revolutionary code analysis tool designed specifically for the AI era. It solves the fundamental problem of LLM token limits when analyzing large code files.
+
+## Core Value Proposition
+
+**Problem**: Large code files (>10K lines) exceed LLM token limits, making AI-assisted code analysis impossible or inefficient.
+
+**Solution**: Smart code analysis that provides:
+- Code structure overview without reading entire files
+- Precise line-range extraction of code sections
+- Accurate positioning data for code operations
+- Native AI assistant integration via MCP protocol
+
+## Target Users
+
+1. **AI Assistant Users**: Developers using Claude Desktop, Cursor, Roo Code, and other AI IDEs
+2. **CLI Users**: Developers who prefer command-line tools for code analysis
+3. **Enterprise Teams**: Organizations dealing with large codebases and AI-assisted development
+
+## Key Features
+
+- **Multi-language Support**: Java, Python, JavaScript/TypeScript (full), C/C++/Rust/Go (basic)
+- **Three-step Workflow**: Scale check → Structure analysis → Code extraction
+- **MCP Integration**: Native support for Model Context Protocol
+- **Enterprise Quality**: 1,358 tests, 74.54% coverage, cross-platform compatibility
+
+## Current Version
+
+v0.9.4 - Latest stable release with comprehensive MCP support and enhanced security features.

tree_sitter_analyzer-0.9.6/.kiro/steering/structure.md

@@ -0,0 +1,197 @@
+# Project Structure & Organization
+
+## Root Directory Layout
+
+```
+tree-sitter-analyzer/
+├── .git/                           # Git repository
+├── .github/                        # GitHub workflows and templates
+├── .kiro/                          # Kiro IDE configuration and steering
+├── tree_sitter_analyzer/          # Main package source code
+├── tests/                          # Comprehensive test suite
+├── examples/                       # Sample files for testing and demos
+├── docs/                           # Documentation
+├── dist/                           # Build artifacts (generated)
+├── .venv/                          # Virtual environment (generated)
+└── Configuration files (see below)
+```
+
+## Core Package Structure (`tree_sitter_analyzer/`)
+
+```
+tree_sitter_analyzer/
+├── __init__.py                     # Package initialization
+├── __main__.py                     # Module entry point
+├── api.py                          # Public API interface
+├── cli_main.py                     # CLI entry point
+├── models.py                       # Data models and types
+├── utils.py                        # Utility functions
+├── exceptions.py                   # Custom exception classes
+├── encoding_utils.py               # File encoding utilities
+├── file_handler.py                 # File operations
+├── language_detector.py            # Language detection logic
+├── language_loader.py              # Tree-sitter language loading
+├── output_manager.py               # Output formatting and display
+├── project_detector.py             # Project root detection
+├── query_loader.py                 # Query management
+├── table_formatter.py              # Table output formatting
+├── core/                           # Core analysis engine
+├── cli/                            # CLI command implementations
+├── formatters/                     # Output formatters
+├── interfaces/                     # Interface adapters (CLI, MCP)
+├── languages/                      # Language-specific plugins
+├── mcp/                            # MCP server implementation
+├── plugins/                        # Plugin system
+├── queries/                        # Tree-sitter queries
+├── security/                       # Security validation
+└── validation/                     # Input validation
+```
+
+## Key Subdirectories
+
+### `core/` - Analysis Engine
+- `analysis_engine.py` - Main analysis orchestration
+- `query_engine.py` - Query execution engine
+- Core business logic for code analysis
+
+### `cli/` - Command Line Interface
+- `commands.py` - CLI command implementations
+- `parser.py` - Argument parsing
+- Command-line specific logic
+
+### `languages/` - Language Plugins
+- `java_plugin.py` - Java language support
+- `python_plugin.py` - Python language support
+- `javascript_plugin.py` - JavaScript language support
+- Language-specific analysis logic
+
+### `mcp/` - Model Context Protocol
+- `server.py` - MCP server implementation
+- `tools.py` - MCP tool definitions
+- AI assistant integration
+
+### `security/` - Security Framework
+- `boundary_manager.py` - Project boundary validation
+- `validator.py` - Input validation and sanitization
+- `regex_checker.py` - Safe regex pattern validation
+
+## Test Structure (`tests/`)
+
+```
+tests/
+├── conftest.py                     # Pytest configuration and fixtures
+├── test_*.py                       # Unit tests (main level)
+├── test_core/                      # Core engine tests
+├── test_interfaces/                # Interface adapter tests
+├── test_languages/                 # Language plugin tests
+├── test_mcp/                       # MCP server tests
+├── test_plugins/                   # Plugin system tests
+├── test_security/                  # Security framework tests
+└── __pycache__/                    # Compiled test files (generated)
+```
+
+## Configuration Files
+
+### Package Configuration
+- `pyproject.toml` - Main package configuration, dependencies, build settings
+- `uv.lock` - Dependency lock file
+- `pytest.ini` - Test configuration
+
+### Code Quality
+- `.pre-commit-config.yaml` - Pre-commit hooks configuration
+- Quality tools configured in `pyproject.toml`
+
+### Documentation
+- `README.md` - Main documentation (English)
+- `README_zh.md` - Chinese documentation
+- `README_ja.md` - Japanese documentation
+- `CONTRIBUTING.md` - Contribution guidelines
+- `CODE_STYLE_GUIDE.md` - Code style standards
+- `CHANGELOG.md` - Version history
+
+### Deployment & Release
+- `DEPLOYMENT_GUIDE.md` - Deployment instructions
+- `PYPI_RELEASE_GUIDE.md` - PyPI release process
+- `upload_to_pypi.py` - Release automation script
+- `build_standalone.py` - Standalone build script
+
+## Examples Directory (`examples/`)
+
+- `BigService.java` - Large Java service class (1419 lines, 66 methods) - main demo file
+- `Sample.java` - Smaller Java example (178 lines, 8 classes)
+- `MultiClass.java` - Multi-class Java example
+- `sample.py` - Python example
+- `*.json` - Analysis result examples
+- Demo and testing files for various languages
+
+## Naming Conventions
+
+### Files and Directories
+- **Snake case** for Python files: `analysis_engine.py`
+- **Lowercase** for directories: `tree_sitter_analyzer/`
+- **Descriptive names** that indicate purpose
+
+### Code Organization
+- **One class per file** when possible
+- **Logical grouping** by functionality
+- **Clear separation** between interfaces, core logic, and plugins
+
+### Import Structure
+```python
+# Standard library imports
+import os
+from pathlib import Path
+
+# Third-party imports
+import tree_sitter
+from typing import Dict, List
+
+# Local imports
+from .models import AnalysisResult
+from .utils import log_info
+```
+
+## Plugin Architecture
+
+### Language Plugins
+- Each language has its own plugin file
+- Plugins implement common interface
+- Dynamic loading and registration
+- Extensible for new languages
+
+### Entry Points
+- Defined in `pyproject.toml`
+- Automatic plugin discovery
+- Support for external plugins
+
+## Security Boundaries
+
+### Project Root Detection
+- Automatic detection from `.git`, `pyproject.toml`, etc.
+- Configurable via CLI `--project-root`
+- Environment variable `TREE_SITTER_PROJECT_ROOT`
+
+### File Access Control
+- All file operations validated against project boundaries
+- Path traversal attack prevention
+- Symlink safety checks
+
+## Build Artifacts (Generated)
+
+### Distribution
+- `dist/` - Wheel and source distributions
+- Built via `uv build`
+
+### Cache Directories
+- `.mypy_cache/` - MyPy type checking cache
+- `.pytest_cache/` - Pytest execution cache
+- `.ruff_cache/` - Ruff linting cache
+- `__pycache__/` - Python bytecode cache
+
+## Development Workflow
+
+1. **Setup**: `uv sync --extra all --extra mcp`
+2. **Code**: Follow structure and naming conventions
+3. **Test**: Add tests in appropriate `test_*/` directories
+4. **Quality**: Run `uv run python check_quality.py --new-code-only --fix`
+5. **Commit**: Pre-commit hooks ensure quality

tree_sitter_analyzer-0.9.6/.kiro/steering/tech.md

@@ -0,0 +1,150 @@
+# Technology Stack & Build System
+
+## Build System & Package Management
+
+- **Primary**: `uv` (fast Python package manager) - used for all development and user installations
+- **Build Backend**: `hatchling` (modern Python build system)
+- **Package Distribution**: PyPI with multiple installation options
+
+## Core Technology Stack
+
+### Language & Runtime
+- **Python**: 3.10+ (required minimum)
+- **Tree-sitter**: v0.24.0 (core parsing engine)
+- **Async Support**: `asyncio` for MCP server operations
+
+### Key Dependencies
+- **MCP**: v1.12.3+ (Model Context Protocol for AI integration)
+- **Character Detection**: `chardet` v5.0.0+ (encoding detection)
+- **Caching**: `cachetools` v5.0.0+ (performance optimization)
+
+### Language Parsers
+- `tree-sitter-java` v0.23.5+
+- `tree-sitter-python` v0.23.6+
+- `tree-sitter-javascript` v0.23.1+
+- `tree-sitter-typescript` v0.20.0+
+- `tree-sitter-cpp` v0.23.4+
+- Additional parsers for C, Rust, Go
+
+## Development Tools
+
+### Code Quality
+- **Formatter**: Black (88 character line length)
+- **Linter**: Ruff (fast Python linter)
+- **Type Checker**: MyPy (with strict configuration)
+- **Import Sorting**: isort (Black-compatible)
+
+### Testing Framework
+- **Test Runner**: pytest v8.4.1+
+- **Coverage**: pytest-cov v4.0.0+
+- **Async Testing**: pytest-asyncio v1.1.0+
+- **Mocking**: pytest-mock v3.14.1+
+
+### Pre-commit Hooks
+- **Setup**: `pre-commit` v3.0.0+
+- **Hooks**: Black, Ruff, MyPy integration
+
+## Common Commands
+
+### Development Setup
+```bash
+# Clone and setup development environment
+git clone https://github.com/aimasteracc/tree-sitter-analyzer.git
+cd tree-sitter-analyzer
+uv sync --extra all --extra mcp
+```
+
+### Testing
+```bash
+# Run all tests (1,358 tests)
+uv run pytest tests/ -v
+
+# Run with coverage report
+uv run pytest tests/ --cov=tree_sitter_analyzer --cov-report=html
+
+# Run specific test categories
+uv run pytest tests/test_mcp_server_initialization.py -v
+uv run pytest tests/test_formatters_comprehensive.py -v
+```
+
+### Code Quality Checks
+```bash
+# Format code
+uv run black .
+
+# Check formatting
+uv run black --check .
+
+# Lint code
+uv run ruff check .
+
+# Auto-fix safe issues
+uv run ruff check . --fix
+
+# Type checking
+uv run mypy .
+
+# Run all quality checks
+uv run python check_quality.py
+
+# Auto-fix and check (recommended for new contributors)
+uv run python check_quality.py --new-code-only --fix
+```
+
+### Building & Distribution
+```bash
+# Build package
+uv build
+
+# Upload to PyPI (maintainers only)
+uv run python upload_to_pypi.py
+```
+
+### CLI Usage
+```bash
+# Basic analysis (large file demo)
+uv run python -m tree_sitter_analyzer examples/BigService.java --advanced --output-format=text
+
+# Structure analysis (66 methods clearly displayed)
+uv run python -m tree_sitter_analyzer examples/BigService.java --table=full
+
+# Partial reading (extract specific code section)
+uv run python -m tree_sitter_analyzer examples/BigService.java --partial-read --start-line 100 --end-line 105
+
+# Quiet mode
+uv run python -m tree_sitter_analyzer examples/BigService.java --table=full --quiet
+```
+
+### MCP Server
+```bash
+# Start MCP server (development)
+uv run python -m tree_sitter_analyzer.mcp.server
+
+# Start with project root
+TREE_SITTER_PROJECT_ROOT=/path/to/project uv run python -m tree_sitter_analyzer.mcp.server
+```
+
+## Installation Options
+
+### End Users
+```bash
+# Basic installation
+uv add tree-sitter-analyzer
+
+# Popular languages (Java, Python, JS, TS)
+uv add "tree-sitter-analyzer[popular]"
+
+# With MCP server support
+uv add "tree-sitter-analyzer[mcp]"
+
+# Full installation
+uv add "tree-sitter-analyzer[all,mcp]"
+```
+
+## Architecture Notes
+
+- **Plugin System**: Dynamic plugin architecture for language support
+- **Caching**: Multi-level caching for parsers and analysis results
+- **Security**: Project boundary validation and input sanitization
+- **Performance**: Optimized for large file handling with minimal memory usage
+- **Cross-platform**: Windows, macOS, Linux compatibility

{tree_sitter_analyzer-0.9.4 → tree_sitter_analyzer-0.9.6}/.pre-commit-config.yaml

@@ -80,11 +80,33 @@ repos:
     hooks:
       - id: quality-check
         name: Tree-sitter Analyzer Quality Check
-        entry: python check_quality.py --new-code-only
+        entry: uv run python check_quality.py --new-code-only
         language: system
         pass_filenames: false
         stages: [pre-push]  # Only run on push
 
+  # README stats update (improved version)
+  - repo: local
+    hooks:
+      - id: update-readme-stats
+        name: Update README Statistics
+        entry: uv run python scripts/improved_readme_updater.py
+        language: system
+        pass_filenames: false
+        stages: [pre-push]  # Only run on push
+        files: ^(README.*\.md|pyproject\.toml|examples/.*\.java)$
+
+  # README stats validation
+  - repo: local
+    hooks:
+      - id: validate-readme-stats
+        name: Validate README Statistics
+        entry: uv run python scripts/improved_readme_updater.py --validate-only
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]  # Run on every commit
+        files: ^README.*\.md$
+
 # Configuration
 default_stages: [pre-commit]
 fail_fast: false

{tree_sitter_analyzer-0.9.4 → tree_sitter_analyzer-0.9.6}/CHANGELOG.md

@@ -1,4 +1,200 @@
 # Changelog
+## [0.9.6] - 2025-01-17
+
+### 🎉 New Feature: Advanced Query Filtering System
+
+#### 🚀 Major Features
+
+##### Smart Query Filtering
+- **Precise Method Search**: Find specific methods using `--filter "name=main"`
+- **Pattern Matching**: Use wildcards like `--filter "name=~auth*"` for authentication-related methods
+- **Parameter Filtering**: Filter by parameter count with `--filter "params=0"`
+- **Modifier Filtering**: Search by visibility and modifiers like `--filter "static=true,public=true"`
+- **Compound Conditions**: Combine multiple filters with `--filter "name=~get*,params=0,public=true"`
+
+##### Unified Architecture
+- **QueryService**: New unified query service eliminates code duplication between CLI and MCP
+- **QueryFilter**: Powerful filtering engine supporting multiple criteria
+- **Consistent API**: Same filtering syntax works in both command line and AI assistants
+
+#### 🛠️ Technical Improvements
+
+##### New Core Components
+- `core/query_service.py`: Unified query execution service
+- `core/query_filter.py`: Advanced result filtering system
+- `cli/commands/query_command.py`: Enhanced CLI query command
+- `mcp/tools/query_tool.py`: New MCP query tool with filtering support
+
+##### Enhanced CLI
+- Added `--filter` argument for query result filtering
+- Added `--filter-help` command to display filter syntax help
+- Improved query command to use unified QueryService
+
+##### MCP Protocol Extensions
+- New `query_code` tool for AI assistants
+- Full filtering support in MCP environment
+- Consistent with CLI filtering syntax
+
+#### 📚 Documentation Updates
+
+##### README Updates
+- **Chinese (README_zh.md)**: Added comprehensive query filtering examples
+- **English (README.md)**: Complete documentation with usage examples
+- **Japanese (README_ja.md)**: Full translation with feature explanations
+
+##### Training Materials
+- Updated `training/01_onboarding.md` with new feature demonstrations
+- Enhanced `training/02_architecture_map.md` with architecture improvements
+- Cross-platform examples for Windows, Linux, and macOS
+
+#### 🧪 Comprehensive Testing
+
+##### Test Coverage
+- **QueryService Tests**: 13 comprehensive unit tests
+- **QueryFilter Tests**: 29 detailed filtering tests  
+- **CLI Integration Tests**: 11 real-world usage scenarios
+- **MCP Tool Tests**: 9 tool definition and functionality tests
+
+##### Test Categories
+- Unit tests for core filtering logic
+- Integration tests with real Java files
+- Edge case handling (overloaded methods, generics, annotations)
+- Error handling and validation
+
+#### 🎯 Usage Examples
+
+##### Command Line Interface
+```bash
+# Find specific method
+uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "name=main"
+
+# Find authentication methods
+uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "name=~auth*"
+
+# Find public methods with no parameters
+uv run python -m tree_sitter_analyzer examples/BigService.java --query-key methods --filter "params=0,public=true"
+
+# View filter syntax help
+uv run python -m tree_sitter_analyzer --filter-help
+```
+
+##### AI Assistant (MCP)
+```json
+{
+  "tool": "query_code",
+  "arguments": {
+    "file_path": "examples/BigService.java",
+    "query_key": "methods",
+    "filter": "name=main"
+  }
+}
+```
+
+#### 🔧 Filter Syntax Reference
+
+##### Supported Filters
+- **name**: Method/function name matching
+  - Exact: `name=main`
+  - Pattern: `name=~auth*` (supports wildcards)
+- **params**: Parameter count filtering
+  - Example: `params=0`, `params=2`
+- **Modifiers**: Visibility and static modifiers
+  - `static=true/false`
+  - `public=true/false`
+  - `private=true/false`
+  - `protected=true/false`
+
+##### Combining Filters
+Use commas for AND logic: `name=~get*,params=0,public=true`
+
+#### 🏗️ Architecture Benefits
+
+##### Code Quality
+- **DRY Principle**: Eliminated duplication between CLI and MCP
+- **Single Responsibility**: Clear separation of concerns
+- **Extensibility**: Easy to add new filter types
+- **Maintainability**: Centralized query logic
+
+##### Performance
+- **Efficient Filtering**: Post-query filtering for optimal performance
+- **Memory Optimized**: Filter after parsing, not during
+- **Scalable**: Works efficiently with large codebases
+
+#### 🚦 Quality Assurance
+
+##### Code Standards
+- **Type Safety**: Full MyPy type annotations
+- **Code Style**: Black formatting, Ruff linting
+- **Documentation**: Comprehensive docstrings and examples
+- **Testing**: 62 new tests with 100% pass rate
+
+##### Platform Support
+- **Windows**: PowerShell examples and testing
+- **Linux/macOS**: Bash examples and compatibility
+- **Codespaces**: Full support for GitHub Codespaces
+
+#### 🎯 Impact
+
+##### Productivity Gains
+- **Faster Code Navigation**: Find specific methods in seconds
+- **Enhanced Code Analysis**: AI assistants can understand code structure better
+- **Reduced Token Usage**: Extract only relevant methods for LLM analysis
+
+##### Integration Benefits
+- **IDE Support**: Works with Cursor, Claude Desktop, Roo Code
+- **CLI Flexibility**: Powerful command-line filtering
+- **API Consistency**: Same functionality across all interfaces
+
+#### 📝 Technical Details
+- **Files Changed**: 15+ core files
+- **New Files**: 6 new modules and test files
+- **Lines Added**: 2000+ lines of code and tests
+- **Documentation**: 500+ lines of updated documentation
+
+#### ✅ Migration Notes
+- All existing CLI and MCP functionality remains compatible
+- New filtering features are additive and optional
+- No breaking changes to existing APIs
+
+---
+
+## [0.9.5] - 2025-01-15
+
+### 🚀 CI/CD Stability & Cross-Platform Compatibility
+- **Enhanced CI Matrix Strategy**: Disabled `fail-fast` strategy for quality-check and test-matrix jobs, ensuring all platform/Python version combinations run to completion
+- **Improved Test Visibility**: Better diagnosis of platform-specific issues with comprehensive matrix results
+- **Cross-Platform Fixes**: Resolved persistent CI failures on Windows, macOS, and Linux
+
+### 🔒 Security Improvements
+- **macOS Symlink Safety**: Fixed symlink safety checks to properly handle macOS temporary directory symlinks (`/var` ↔ `/private/var`)
+- **Project Boundary Management**: Enhanced boundary detection to correctly handle real paths within project boundaries
+- **Security Code Quality**: Addressed all Bandit security linter low-risk findings:
+  - Replaced bare `pass` statements with explicit `...` for better intent documentation
+  - Added proper attribute checks for `sys.stderr` writes
+  - Replaced runtime `assert` statements with defensive type checking
+
+### 📊 Documentation & Structure
+- **README Enhancement**: Complete restructure with table of contents, improved content flow, and visual hierarchy
+- **Multi-language Support**: Fully translated README into Chinese (`README_zh.md`) and Japanese (`README_ja.md`)
+- **Documentation Standards**: Normalized line endings across all markdown files
+- **Project Guidelines**: Added new language development guidelines and project structure documentation
+
+### 🛠️ Code Quality Enhancements
+- **Error Handling**: Improved robustness in `encoding_utils.py` and `utils.py` with better exception handling patterns
+- **Platform Compatibility**: Enhanced test assertions for cross-platform compatibility
+- **Security Practices**: Strengthened security validation while maintaining usability
+
+### 🧪 Testing & Quality Assurance
+- **Test Suite**: 1,358 tests passing with 74.54% coverage
+- **Platform Coverage**: Full testing across Python 3.10-3.13 × Windows/macOS/Linux
+- **CI Reliability**: Stable CI pipeline with comprehensive error reporting
+
+### 🚀 Impact
+- **Enterprise Ready**: Improved stability for production deployments
+- **Developer Experience**: Better local development workflow with consistent tooling
+- **AI Integration**: Enhanced MCP protocol compatibility across all supported platforms
+- **International Reach**: Multi-language documentation for global developer community
+
 ## [0.9.4] - 2025-08-15
 
 ### 🔧 Fixed (MCP)

{tree_sitter_analyzer-0.9.4 → tree_sitter_analyzer-0.9.6}/CONTRIBUTING.md

@@ -20,7 +20,7 @@ uv run python -c "import tree_sitter_analyzer; print('Setup OK')"
 
 ### Running Tests
 
-> 本项目在所有本地命令中统一使用 `uv run`（Windows/PowerShell 亦同）。请不要直接调用裸 `pytest` 或 `python`，以确保一致的解释器与虚拟环境。
+> This project uses `uv run` for all local commands (including Windows/PowerShell). Do not call `pytest` or `python` directly to ensure consistent interpreter and virtual environment.
 
 ```bash
 # Run all tests (1216+ tests)
@@ -190,4 +190,50 @@ This will auto-format your code and fix safe issues while skipping the ~300 lega
 - Add docstrings to new functions/classes
 - Update MCP setup guides if needed
 
-Thank you for contributing! 🎉
+## 📊 README Data Maintenance
+
+**Important:** README files contain dynamic statistics that need regular updates!
+
+### Data That Needs Synchronization
+
+1. **Test Statistics**
+   - Test count: `1,358 tests`
+   - Code coverage: `74.54%`
+   - Location: Badges and quality metrics sections
+
+2. **Version Information**
+   - Current version: From `pyproject.toml`
+   - Location: Quality achievements section
+
+3. **Example File Statistics**
+   - BigService.java lines: `1419 lines`
+   - Method count: `66 methods`
+   - Field count: `9 fields`
+   - Class count: `1 class`
+   - Import count: `8 imports`
+
+### Auto-update README Statistics
+```bash
+# Run this script after significant changes
+python scripts/update_readme_stats.py
+```
+
+### When to Update
+- Add/remove test files
+- Modify examples/BigService.java
+- Update version numbers in pyproject.toml
+- Before releases
+- After major feature additions
+
+### Automated Checks
+- **Pre-commit Hook**: Runs on `git push`
+- **GitHub Actions**: Validates README consistency on PRs
+- **CI/CD**: Ensures main branch README is always current
+
+### Development Workflow
+1. Make code changes
+2. Run quality checks: `uv run python check_quality.py --new-code-only --fix`
+3. Update README stats: `python scripts/update_readme_stats.py`
+4. Commit and push changes
+
+Thank you for contributing! 🎉