tree-sitter-analyzer 0.8.2__tar.gz → 0.9.1__tar.gz

{tree_sitter_analyzer-0.8.2 → tree_sitter_analyzer-0.9.1}/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.1] - 2025-08-12
+
+### 🎯 MCP Tools Unification & Simplification
+
+#### 🔧 Unified Tool Names
+- **BREAKING**: Simplified MCP tools to 3 core tools with clear naming:
+  - `check_code_scale` - Step 1: Check file scale and complexity
+  - `analyze_code_structure` - Step 2: Generate structure tables with line positions
+  - `extract_code_section` - Step 3: Extract specific code sections by line range
+- **Removed**: Backward compatibility for old tool names (`analyze_code_scale`, `read_code_partial`, `format_table`, `analyze_code_universal`)
+- **Enhanced**: Tool descriptions with step numbers and usage guidance
+
+#### 📋 Parameter Standardization
+- **Standardized**: All parameters use snake_case naming convention
+- **Fixed**: Common LLM parameter mistakes with clear validation
+- **Required**: `file_path` parameter for all tools
+- **Required**: `start_line` parameter for `extract_code_section`
+
+#### 📖 Documentation Improvements
+- **Updated**: README.md with unified tool workflow examples
+- **Enhanced**: MCP_INFO with workflow guidance
+- **Simplified**: Removed redundant documentation files
+- **Added**: Clear three-step workflow instructions for LLMs
+
+#### 🧪 Test Suite Updates
+- **Fixed**: All MCP-related tests updated for new tool names
+- **Updated**: 138 MCP tests passing with new unified structure
+- **Enhanced**: Test coverage for unified tool workflow
+- **Maintained**: 100% backward compatibility in core analysis engine
+
+#### 🎉 Benefits
+- **Simplified**: LLM integration with clear tool naming
+- **Reduced**: Parameter confusion with consistent snake_case
+- **Improved**: Workflow clarity with numbered steps
+- **Enhanced**: Error messages with available tool suggestions
+
 ## [0.8.2] - 2025-08-05
 
 ### 🎯 Major Quality Improvements

{tree_sitter_analyzer-0.8.2 → tree_sitter_analyzer-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tree-sitter-analyzer
-Version: 0.8.2
+Version: 0.9.1
 Summary: Extensible multi-language code analyzer framework using Tree-sitter with dynamic plugin architecture
 Project-URL: Homepage, https://github.com/aimasteracc/tree-sitter-analyzer
 Project-URL: Documentation, https://github.com/aimasteracc/tree-sitter-analyzer#readme
@@ -137,7 +137,7 @@ Description-Content-Type: text/markdown
 
 [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-1358%20passed-brightgreen.svg)](#testing)
+[![Tests](https://img.shields.io/badge/tests-306%20passed-brightgreen.svg)](#testing)
 [![Coverage](https://img.shields.io/badge/coverage-74.82%25-green.svg)](#testing)
 [![Quality](https://img.shields.io/badge/quality-enterprise%20grade-blue.svg)](#quality)
 
@@ -228,11 +228,10 @@ Extract specific code sections efficiently:
 - Content length information
 
 ### 3. AI Assistant Integration
-Four powerful MCP tools for AI assistants:
-- `analyze_code_scale` - Get code metrics and complexity
-- `analyze_code_structure` - Generate detailed structure tables
-- `read_code_partial` - Extract specific line ranges
-- `analyze_code_universal` - Universal analysis with auto-detection
+Three-step workflow MCP tools for AI assistants:
+- `check_code_scale` - **Step 1:** Get code metrics and complexity
+- `analyze_code_structure` - **Step 2:** Generate detailed structure tables with line positions
+- `extract_code_section` - **Step 3:** Extract specific code sections by line range
 
 ### 4. Multi-Language Support
 - **Java** - Full support with advanced analysis
@@ -244,14 +243,25 @@ Four powerful MCP tools for AI assistants:
 
 ### AI Assistant Usage (via Claude Desktop)
 
-**Step 1: Get code overview:**
-> "What's the overall complexity and size of this Java file examples/Sample.java?"
+**Step 1: Check code scale**
+```
+Use tool: check_code_scale
+Parameters: {"file_path": "examples/Sample.java"}
+```
 
-**Step 2: Analyze code structure (for large files):**
-> "Please analyze the structure of examples/Sample.java and show me a detailed table"
+**Step 2: Analyze structure (for large files >100 lines)**
+```
+Use tool: analyze_code_structure
+Parameters: {"file_path": "examples/Sample.java", "format_type": "full"}
+```
+
+**Step 3: Extract specific code (using line positions from step 2)**
+```
+Use tool: extract_code_section
+Parameters: {"file_path": "examples/Sample.java", "start_line": 84, "end_line": 86}
+```
 
-**Step 3: Extract specific code:**
-> "Show me lines 84-86 from examples/Sample.java"
+> **Note:** Always use snake_case parameter names: `file_path`, `start_line`, `end_line`, `format_type`
 
 ### CLI Usage
 

{tree_sitter_analyzer-0.8.2 → tree_sitter_analyzer-0.9.1}/PROJECT_ROOT_CONFIG.md

@@ -1,203 +1,203 @@
-# Project Root Configuration Guide
-
-**Quick reference for configuring project root in tree-sitter-analyzer**
-
-## 🎯 Recommended Configuration (Most Users)
-
-### MCP Server (Claude Desktop)
-
-```json
-{
-  "mcpServers": {
-    "tree-sitter-analyzer": {
-      "command": "uv",
-      "args": [
-        "run", "--with", "tree-sitter-analyzer[mcp]",
-        "python", "-m", "tree_sitter_analyzer.mcp.server"
-      ],
-      "env": {
-        "TREE_SITTER_PROJECT_ROOT": "${workspaceFolder}"
-      }
-    }
-  }
-}
-```
-
-### CLI Usage
-
-```bash
-# Auto-detect project root (recommended)
-tree-sitter-analyzer src/main.py --table=full
-
-# Explicit project root (when needed)
-tree-sitter-analyzer src/main.py --project-root /path/to/project --table=full
-```
-
-## 🔧 How It Works
-
-### Auto-Detection Process
-
-1. **Searches for project markers** (in priority order):
-   - Version control: `.git`, `.hg`, `.svn`
-   - Python: `pyproject.toml`, `setup.py`, `requirements.txt`
-   - JavaScript: `package.json`, `yarn.lock`, `node_modules`
-   - Java: `pom.xml`, `build.gradle`, `gradlew`
-   - And 20+ more project types
-
-2. **Traverses upward** from file location
-3. **Selects best match** based on marker priority and count
-4. **Falls back** to file directory if no markers found
-
-### Security Benefits
-
-- ✅ **File access control**: Only files within project boundaries
-- ✅ **Path traversal protection**: Blocks `../../../etc/passwd` attacks
-- ✅ **Symlink safety**: Prevents symlink-based boundary bypass
-- ✅ **Audit logging**: Records all security events
-
-## 📋 Configuration Options
-
-### Priority Order (Highest to Lowest)
-
-| Priority | Method | CLI | MCP | Use Case |
-|----------|--------|-----|-----|----------|
-| 🥇 **1st** | Command line argument | `--project-root /path` | `"args": [..., "--project-root", "/path"]` | Fixed paths, overrides |
-| 🥈 **2nd** | Environment variable | `TREE_SITTER_PROJECT_ROOT=/path` | `"env": {"TREE_SITTER_PROJECT_ROOT": "/path"}` | Dynamic, workspace integration |
-| 🥉 **3rd** | Auto-detection | *(default)* | *(default)* | Zero configuration |
-
-### When to Use Each Method
-
-#### Environment Variable (Recommended)
-```json
-"env": {"TREE_SITTER_PROJECT_ROOT": "${workspaceFolder}"}
-```
-- ✅ **Best for**: Most users, IDE integration
-- ✅ **Benefits**: Automatic workspace adaptation, flexible
-- ✅ **Works with**: VS Code, most IDEs
-
-#### Command Line Argument
-```bash
---project-root /specific/path
-```
-- ✅ **Best for**: Fixed paths, CI/CD, overrides
-- ✅ **Benefits**: Explicit control, highest priority
-- ✅ **Works with**: Scripts, automation
-
-#### Auto-Detection
-```bash
-# No configuration needed
-```
-- ✅ **Best for**: Development, quick testing
-- ✅ **Benefits**: Zero configuration, intelligent
-- ✅ **Works with**: Standard project structures
-
-## 🚨 Common Issues & Solutions
-
-### Issue: "Absolute path must be within project directory"
-
-**Cause**: File is outside detected project boundary
-
-**Solutions:**
-1. Use explicit project root: `--project-root /correct/path`
-2. Check project markers exist in expected location
-3. Verify file is actually within intended project
-
-### Issue: "No project root detected"
-
-**Cause**: No project markers found
-
-**Solutions:**
-1. Add a project marker file (`.git`, `pyproject.toml`, etc.)
-2. Use explicit project root: `--project-root .`
-3. Check current working directory
-
-### Issue: Wrong project root detected
-
-**Cause**: Multiple nested projects or unexpected markers
-
-**Solutions:**
-1. Use explicit project root to override
-2. Remove unwanted project markers
-3. Check marker priority (`.git` > `pyproject.toml` > `README.md`)
-
-## 🧪 Testing Your Configuration
-
-### Test Auto-Detection
-```bash
-cd /your/project
-python -c "
-from tree_sitter_analyzer.project_detector import detect_project_root
-print('Detected:', detect_project_root())
-"
-```
-
-### Test MCP Server
-```bash
-# Test with your configuration
-python -m tree_sitter_analyzer.mcp.server --help
-# Check logs for "MCP server starting with project root: ..."
-```
-
-### Test Security Boundaries
-```bash
-# Should work (file within project)
-tree-sitter-analyzer src/main.py --table=compact
-
-# Should fail (file outside project)
-tree-sitter-analyzer ../outside.py --table=compact
-```
-
-## 📖 Examples by Project Type
-
-### Python Project
-```
-my-python-project/
-├── pyproject.toml          # ← Detected as project root
-├── src/
-│   └── mypackage/
-│       └── main.py         # ← Analyze this file
-└── tests/
-```
-
-### JavaScript Project
-```
-my-js-project/
-├── package.json            # ← Detected as project root
-├── src/
-│   └── index.js           # ← Analyze this file
-└── node_modules/
-```
-
-### Java Project
-```
-my-java-project/
-├── pom.xml                 # ← Detected as project root
-├── src/
-│   └── main/
-│       └── java/
-│           └── Main.java   # ← Analyze this file
-└── target/
-```
-
-### Git Repository
-```
-any-project/
-├── .git/                   # ← Detected as project root (highest priority)
-├── src/
-│   └── code.ext           # ← Analyze this file
-└── docs/
-```
-
-## 🎯 Best Practices
-
-1. **Use environment variable for MCP**: `${workspaceFolder}` adapts automatically
-2. **Let auto-detection work**: Most projects have standard markers
-3. **Override when needed**: Use command line for special cases
-4. **Test your setup**: Verify project root detection works as expected
-5. **Keep it simple**: Start with recommended configuration, customize only if needed
-
----
-
-**Need help?** Check the full setup guides:
-- [MCP Setup for Users](MCP_SETUP_USERS.md)
-- [MCP Setup for Developers](MCP_SETUP_DEVELOPERS.md)
+# Project Root Configuration Guide
+
+**Quick reference for configuring project root in tree-sitter-analyzer**
+
+## 🎯 Recommended Configuration (Most Users)
+
+### MCP Server (Claude Desktop)
+
+```json
+{
+  "mcpServers": {
+    "tree-sitter-analyzer": {
+      "command": "uv",
+      "args": [
+        "run", "--with", "tree-sitter-analyzer[mcp]",
+        "python", "-m", "tree_sitter_analyzer.mcp.server"
+      ],
+      "env": {
+        "TREE_SITTER_PROJECT_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+### CLI Usage
+
+```bash
+# Auto-detect project root (recommended)
+tree-sitter-analyzer src/main.py --table=full
+
+# Explicit project root (when needed)
+tree-sitter-analyzer src/main.py --project-root /path/to/project --table=full
+```
+
+## 🔧 How It Works
+
+### Auto-Detection Process
+
+1. **Searches for project markers** (in priority order):
+   - Version control: `.git`, `.hg`, `.svn`
+   - Python: `pyproject.toml`, `setup.py`, `requirements.txt`
+   - JavaScript: `package.json`, `yarn.lock`, `node_modules`
+   - Java: `pom.xml`, `build.gradle`, `gradlew`
+   - And 20+ more project types
+
+2. **Traverses upward** from file location
+3. **Selects best match** based on marker priority and count
+4. **Falls back** to file directory if no markers found
+
+### Security Benefits
+
+- ✅ **File access control**: Only files within project boundaries
+- ✅ **Path traversal protection**: Blocks `../../../etc/passwd` attacks
+- ✅ **Symlink safety**: Prevents symlink-based boundary bypass
+- ✅ **Audit logging**: Records all security events
+
+## 📋 Configuration Options
+
+### Priority Order (Highest to Lowest)
+
+| Priority | Method | CLI | MCP | Use Case |
+|----------|--------|-----|-----|----------|
+| 🥇 **1st** | Command line argument | `--project-root /path` | `"args": [..., "--project-root", "/path"]` | Fixed paths, overrides |
+| 🥈 **2nd** | Environment variable | `TREE_SITTER_PROJECT_ROOT=/path` | `"env": {"TREE_SITTER_PROJECT_ROOT": "/path"}` | Dynamic, workspace integration |
+| 🥉 **3rd** | Auto-detection | *(default)* | *(default)* | Zero configuration |
+
+### When to Use Each Method
+
+#### Environment Variable (Recommended)
+```json
+"env": {"TREE_SITTER_PROJECT_ROOT": "${workspaceFolder}"}
+```
+- ✅ **Best for**: Most users, IDE integration
+- ✅ **Benefits**: Automatic workspace adaptation, flexible
+- ✅ **Works with**: VS Code, most IDEs
+
+#### Command Line Argument
+```bash
+--project-root /specific/path
+```
+- ✅ **Best for**: Fixed paths, CI/CD, overrides
+- ✅ **Benefits**: Explicit control, highest priority
+- ✅ **Works with**: Scripts, automation
+
+#### Auto-Detection
+```bash
+# No configuration needed
+```
+- ✅ **Best for**: Development, quick testing
+- ✅ **Benefits**: Zero configuration, intelligent
+- ✅ **Works with**: Standard project structures
+
+## 🚨 Common Issues & Solutions
+
+### Issue: "Absolute path must be within project directory"
+
+**Cause**: File is outside detected project boundary
+
+**Solutions:**
+1. Use explicit project root: `--project-root /correct/path`
+2. Check project markers exist in expected location
+3. Verify file is actually within intended project
+
+### Issue: "No project root detected"
+
+**Cause**: No project markers found
+
+**Solutions:**
+1. Add a project marker file (`.git`, `pyproject.toml`, etc.)
+2. Use explicit project root: `--project-root .`
+3. Check current working directory
+
+### Issue: Wrong project root detected
+
+**Cause**: Multiple nested projects or unexpected markers
+
+**Solutions:**
+1. Use explicit project root to override
+2. Remove unwanted project markers
+3. Check marker priority (`.git` > `pyproject.toml` > `README.md`)
+
+## 🧪 Testing Your Configuration
+
+### Test Auto-Detection
+```bash
+cd /your/project
+python -c "
+from tree_sitter_analyzer.project_detector import detect_project_root
+print('Detected:', detect_project_root())
+"
+```
+
+### Test MCP Server
+```bash
+# Test with your configuration
+python -m tree_sitter_analyzer.mcp.server --help
+# Check logs for "MCP server starting with project root: ..."
+```
+
+### Test Security Boundaries
+```bash
+# Should work (file within project)
+tree-sitter-analyzer src/main.py --table=compact
+
+# Should fail (file outside project)
+tree-sitter-analyzer ../outside.py --table=compact
+```
+
+## 📖 Examples by Project Type
+
+### Python Project
+```
+my-python-project/
+├── pyproject.toml          # ← Detected as project root
+├── src/
+│   └── mypackage/
+│       └── main.py         # ← Analyze this file
+└── tests/
+```
+
+### JavaScript Project
+```
+my-js-project/
+├── package.json            # ← Detected as project root
+├── src/
+│   └── index.js           # ← Analyze this file
+└── node_modules/
+```
+
+### Java Project
+```
+my-java-project/
+├── pom.xml                 # ← Detected as project root
+├── src/
+│   └── main/
+│       └── java/
+│           └── Main.java   # ← Analyze this file
+└── target/
+```
+
+### Git Repository
+```
+any-project/
+├── .git/                   # ← Detected as project root (highest priority)
+├── src/
+│   └── code.ext           # ← Analyze this file
+└── docs/
+```
+
+## 🎯 Best Practices
+
+1. **Use environment variable for MCP**: `${workspaceFolder}` adapts automatically
+2. **Let auto-detection work**: Most projects have standard markers
+3. **Override when needed**: Use command line for special cases
+4. **Test your setup**: Verify project root detection works as expected
+5. **Keep it simple**: Start with recommended configuration, customize only if needed
+
+---
+
+**Need help?** Check the full setup guides:
+- [MCP Setup for Users](MCP_SETUP_USERS.md)
+- [MCP Setup for Developers](MCP_SETUP_DEVELOPERS.md)

tree_sitter_analyzer-0.9.1/PYPI_RELEASE_GUIDE.md

@@ -0,0 +1,125 @@
+# PyPI Release Guide for tree-sitter-analyzer v0.9.1
+
+## 📦 Package Ready for Release
+
+✅ **All tests passed**: 306 tests  
+✅ **Package built**: `dist/tree_sitter_analyzer-0.9.1-py3-none-any.whl`  
+✅ **Source distribution**: `dist/tree_sitter_analyzer-0.9.1.tar.gz`  
+✅ **Documentation updated**: README, CHANGELOG, release notes  
+✅ **GitHub released**: Tagged v0.9.1 and pushed  
+
+## 🚀 Manual PyPI Release Steps
+
+### Option 1: Using uv (Recommended)
+
+1. **Get PyPI API Token**:
+   - Go to https://pypi.org/account/register/ (create account if needed)
+   - Go to https://pypi.org/manage/account/token/
+   - Create a new API token with scope "Entire account"
+   - Copy the token (starts with `pypi-`)
+
+2. **Set Environment Variable**:
+   ```bash
+   # Windows
+   set UV_PUBLISH_TOKEN=pypi-your-token-here
+   
+   # Linux/Mac
+   export UV_PUBLISH_TOKEN=pypi-your-token-here
+   ```
+
+3. **Upload to PyPI**:
+   ```bash
+   uv publish
+   ```
+
+### Option 2: Using twine
+
+1. **Install twine**:
+   ```bash
+   uv add --dev twine
+   ```
+
+2. **Upload to PyPI**:
+   ```bash
+   uv run twine upload dist/*
+   ```
+   - Enter username: `__token__`
+   - Enter password: `pypi-your-token-here`
+
+### Option 3: Test PyPI First (Recommended)
+
+1. **Upload to Test PyPI**:
+   ```bash
+   uv publish --publish-url https://test.pypi.org/legacy/ --token pypi-your-test-token
+   ```
+
+2. **Test Installation**:
+   ```bash
+   pip install --index-url https://test.pypi.org/simple/ tree-sitter-analyzer==0.9.1
+   ```
+
+3. **If successful, upload to production PyPI**:
+   ```bash
+   uv publish --token pypi-your-production-token
+   ```
+
+## 📋 Pre-Release Checklist
+
+- [x] All tests pass (306/306)
+- [x] Version updated in pyproject.toml (0.9.1)
+- [x] Version updated in __init__.py (0.9.1)
+- [x] CHANGELOG.md updated
+- [x] README.md updated
+- [x] Release notes created
+- [x] Git tagged and pushed
+- [x] Package built successfully
+- [x] Package integrity verified
+
+## 🎯 Release Highlights
+
+### MCP Tools Unification
+- **check_code_scale**: STEP 1 - Check file scale and complexity
+- **analyze_code_structure**: STEP 2 - Generate structure tables with line positions  
+- **extract_code_section**: STEP 3 - Extract specific code sections
+
+### Key Benefits
+- Clear 3-step workflow for LLMs
+- Consistent snake_case parameter naming
+- Enhanced error messages and guidance
+- Simplified codebase (removed backward compatibility)
+- 306 comprehensive tests
+
+## 📊 Test Results Summary
+
+```
+MCP Tests:           103 passed ✅
+Core Tests:          168 passed ✅  
+MCP Server Tests:     35 passed ✅
+Total:               306 passed ✅
+```
+
+## 🔗 Post-Release Actions
+
+After successful PyPI upload:
+
+1. **Verify Installation**:
+   ```bash
+   pip install tree-sitter-analyzer==0.9.1
+   python -c "import tree_sitter_analyzer; print(tree_sitter_analyzer.__version__)"
+   ```
+
+2. **Update Documentation**:
+   - Update installation instructions
+   - Announce on relevant channels
+   - Update project status
+
+3. **GitHub Release**:
+   - Create GitHub release from tag v0.9.1
+   - Attach release notes
+   - Include built packages
+
+## 🎉 Ready to Release!
+
+The package is fully tested and ready for PyPI release. All 306 tests pass, documentation is complete, and the MCP tools unification provides significant improvements for LLM integration.
+
+**This release represents a major improvement in usability for AI assistants working with large codebases!**