tree-sitter-analyzer 0.9.3__tar.gz → 0.9.5__tar.gz

tree_sitter_analyzer-0.9.5/.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.5/.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.5/.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.3 → tree_sitter_analyzer-0.9.5}/.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.3 → tree_sitter_analyzer-0.9.5}/AI_COLLABORATION_GUIDE.md

@@ -10,10 +10,10 @@ Before generating any code, AI systems should run these commands to understand t
 
 ```bash
 # 1. Check current code quality
-python check_quality.py --new-code-only
+uv run python check_quality.py --new-code-only
 
 # 2. Run LLM-specific code checker
-python llm_code_checker.py --check-all
+uv run python llm_code_checker.py --check-all
 
 # 3. Review test coverage
 uv run pytest tests/ --cov=tree_sitter_analyzer --cov-report=term-missing
@@ -48,10 +48,10 @@ find tree_sitter_analyzer -name "*.py" | head -20
    uv run pytest tests/ -v
    
    # LLM-specific checks
-   python llm_code_checker.py [new_file.py]
+   uv run python llm_code_checker.py [new_file.py]
    
    # Final quality check
-   python check_quality.py
+   uv run python check_quality.py
    ```
 
 ### Mandatory Patterns
@@ -96,7 +96,7 @@ def analyze_code(file_path: str, options: Optional[Dict[str, Any]] = None) -> An
 
 AI-generated code MUST pass all these checks:
 
-- [ ] ✅ `python llm_code_checker.py [file]` - No issues
+- [ ] ✅ `uv run python llm_code_checker.py [file]` - No issues
 - [ ] ✅ `uv run black --check .` - Properly formatted
 - [ ] ✅ `uv run ruff check .` - No linting errors
 - [ ] ✅ `uv run mypy tree_sitter_analyzer/` - Type checks pass
@@ -115,10 +115,10 @@ When reviewing AI-generated code:
 
 ```bash
 # Quick quality check
-python llm_code_checker.py path/to/ai_generated_file.py
+uv run python llm_code_checker.py path/to/ai_generated_file.py
 
 # Comprehensive review
-python check_quality.py --new-code-only
+uv run python check_quality.py --new-code-only
 ```
 
 #### 2. Common AI Code Issues
@@ -135,16 +135,16 @@ Watch out for these common problems:
 
 ```bash
 # 1. Run AI code checker
-python llm_code_checker.py ai_generated_file.py
+uv run python llm_code_checker.py ai_generated_file.py
 
 # 2. Fix identified issues
 # [Manual fixes based on checker output]
 
 # 3. Verify fixes
-python llm_code_checker.py ai_generated_file.py
+uv run python llm_code_checker.py ai_generated_file.py
 
 # 4. Run full quality check
-python check_quality.py
+uv run python check_quality.py
 ```
 
 ### Requesting AI Assistance
@@ -183,16 +183,16 @@ Always provide:
 
 ```bash
 # Check specific AI-generated file
-python llm_code_checker.py tree_sitter_analyzer/new_feature.py
+uv run python llm_code_checker.py tree_sitter_analyzer/new_feature.py
 
 # Check all files for AI-specific issues
-python llm_code_checker.py --check-all
+uv run python llm_code_checker.py --check-all
 
 # Run comprehensive quality check
-python check_quality.py
+uv run python check_quality.py
 
 # Check only new/modified code
-python check_quality.py --new-code-only
+uv run python check_quality.py --new-code-only
 
 # Auto-fix common issues
 uv run black . && uv run isort . && uv run ruff check . --fix
@@ -206,11 +206,11 @@ AI-generated code should achieve:
 
 | Metric | Target | Command |
 |--------|--------|---------|
-| Test Coverage | ≥90% | `pytest --cov=tree_sitter_analyzer` |
-| Type Coverage | 100% | `mypy tree_sitter_analyzer/` |
-| Linting Score | 0 errors | `ruff check .` |
+| Test Coverage | ≥90% | `uv run pytest --cov=tree_sitter_analyzer` |
+| Type Coverage | 100% | `uv run mypy tree_sitter_analyzer/` |
+| Linting Score | 0 errors | `uv run ruff check .` |
 | Security Score | 0 issues | `bandit -r tree_sitter_analyzer/` |
-| Documentation | 100% public APIs | `llm_code_checker.py` |
+| Documentation | 100% public APIs | `uv run python llm_code_checker.py` |
 
 ### Performance Benchmarks