tree-sitter-analyzer 0.8.0__tar.gz → 0.8.1__tar.gz

{tree_sitter_analyzer-0.8.0 → tree_sitter_analyzer-0.8.1}/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.8.1] - 2025-08-05
+
+### 🔧 Fixed
+- **Fixed**: Eliminated duplicate "ERROR:" prefixes in error messages across all CLI commands
+- **Fixed**: Updated all CLI tests to match unified error message format
+- **Fixed**: Resolved missing `--project-root` parameters in comprehensive CLI tests
+- **Fixed**: Corrected module import issues in language detection tests
+- **Fixed**: Updated test expectations to match security validation behavior
+
+### 🧪 Testing Improvements
+- **Enhanced**: Fixed 6 failing tests in `test_partial_read_command_validation.py`
+- **Enhanced**: Fixed 6 failing tests in `test_cli_comprehensive.py` and Java structure analyzer tests
+- **Enhanced**: Improved test stability and reliability across all CLI functionality
+- **Enhanced**: Unified error message testing with consistent format expectations
+
+### 📦 Code Quality
+- **Improved**: Centralized error message formatting in `output_manager.py`
+- **Improved**: Consistent error handling architecture across all CLI commands
+- **Improved**: Better separation of concerns between error content and formatting
+
+---
+
 ## [0.8.0] - 2025-08-04
 
 ### 🚀 Added

tree_sitter_analyzer-0.8.1/MCP_SETUP_DEVELOPERS.md

@@ -0,0 +1,325 @@
+# MCP Setup Guide for Developers
+
+**Local development setup for Tree-sitter Analyzer MCP server**
+
+## Prerequisites
+
+- Python 3.10+
+- uv package manager
+- Git
+- Claude Desktop (for testing)
+
+## Development Setup
+
+### 1. Clone and Setup Project
+
+```bash
+# Clone the repository
+git clone https://github.com/aimasteracc/tree-sitter-analyzer.git
+cd tree-sitter-analyzer
+
+# Install development dependencies
+uv sync --extra all --extra mcp
+
+# Verify installation
+uv run python -c "import tree_sitter_analyzer; print('Development setup OK')"
+```
+
+### 2. Configure Claude Desktop for Local Development
+
+#### Recommended Development Configuration
+
+```json
+{
+  "mcpServers": {
+    "tree-sitter-analyzer-dev": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/absolute/path/to/tree-sitter-analyzer",
+        "python",
+        "-m",
+        "tree_sitter_analyzer.mcp.server"
+      ],
+      "env": {
+        "TREE_SITTER_PROJECT_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+**Important:** Replace `/absolute/path/to/tree-sitter-analyzer` with your actual project path.
+
+## Project Root Configuration Options
+
+The MCP server supports multiple ways to configure the project root directory for security and functionality:
+
+### Configuration Priority (Highest to Lowest)
+
+1. **Command Line Argument** (Highest Priority)
+2. **Environment Variable** (Medium Priority)
+3. **Auto-Detection** (Lowest Priority)
+
+### Option 1: Environment Variable (Recommended)
+
+```json
+{
+  "mcpServers": {
+    "tree-sitter-analyzer-dev": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/tree-sitter-analyzer", "python", "-m", "tree_sitter_analyzer.mcp.server"],
+      "env": {
+        "TREE_SITTER_PROJECT_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+**Benefits:**
+- ✅ Automatically adapts to current workspace
+- ✅ Works with any IDE supporting workspace variables
+- ✅ Flexible and dynamic configuration
+
+### Option 2: Command Line Argument
+
+```json
+{
+  "mcpServers": {
+    "tree-sitter-analyzer-dev": {
+      "command": "uv",
+      "args": [
+        "run", "--directory", "/path/to/tree-sitter-analyzer",
+        "python", "-m", "tree_sitter_analyzer.mcp.server",
+        "--project-root", "/specific/project/path"
+      ]
+    }
+  }
+}
+```
+
+**Use cases:**
+- 🎯 Fixed project path requirements
+- 🎯 Override environment variable settings
+- 🎯 Multi-project environments
+
+### Option 3: Auto-Detection (Zero Configuration)
+
+```json
+{
+  "mcpServers": {
+    "tree-sitter-analyzer-dev": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/tree-sitter-analyzer", "python", "-m", "tree_sitter_analyzer.mcp.server"]
+    }
+  }
+}
+```
+
+**How it works:**
+- 🔍 Searches for project markers (.git, pyproject.toml, package.json, etc.)
+- 🔍 Traverses up directory tree from server working directory
+- 🔍 Falls back to current working directory if no markers found
+
+**Supported project markers:**
+- 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 many more...
+
+## Testing Project Root Configuration
+
+### Test Auto-Detection
+
+```bash
+# Test from project directory
+cd /your/project/directory
+uv run python -m tree_sitter_analyzer.mcp.server --help
+
+# Should show detected project root in logs
+```
+
+### Test Command Line Override
+
+```bash
+# Test explicit project root
+uv run python -m tree_sitter_analyzer.mcp.server --project-root /specific/path --help
+```
+
+### Test Environment Variable
+
+```bash
+# Test environment variable
+export TREE_SITTER_PROJECT_ROOT=/your/project
+uv run python -m tree_sitter_analyzer.mcp.server --help
+```
+
+### Test Priority Handling
+
+```bash
+# Test priority (command line should win)
+export TREE_SITTER_PROJECT_ROOT=/env/path
+uv run python -m tree_sitter_analyzer.mcp.server --project-root /cmd/path --help
+# Should use /cmd/path
+```
+
+## Debugging Project Root Issues
+
+### Check Current Configuration
+
+```bash
+# Run with verbose logging
+uv run python -c "
+from tree_sitter_analyzer.project_detector import detect_project_root
+import logging
+logging.basicConfig(level=logging.INFO)
+result = detect_project_root()
+print(f'Detected project root: {result}')
+"
+```
+
+### Verify Security Boundaries
+
+```bash
+# Test file access validation
+uv run python -c "
+from tree_sitter_analyzer.security import SecurityValidator
+validator = SecurityValidator('/your/project/root')
+is_valid, msg = validator.validate_file_path('/your/project/root/src/file.py')
+print(f'Valid: {is_valid}, Message: {msg}')
+"
+```
+
+### 3. Dual Configuration (Development + Stable)
+
+For testing both versions, use this configuration:
+
+```json
+{
+  "mcpServers": {
+    "tree-sitter-analyzer-dev": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/your/tree-sitter-analyzer",
+        "python",
+        "-m",
+        "tree_sitter_analyzer.mcp.server"
+      ],
+      "disabled": false
+    },
+    "tree-sitter-analyzer-stable": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--with",
+        "tree-sitter-analyzer[mcp]",
+        "python",
+        "-m",
+        "tree_sitter_analyzer.mcp.server"
+      ],
+      "disabled": true
+    }
+  }
+}
+```
+
+Switch between versions by changing the `disabled` flag.
+
+## Development Workflow
+
+### 1. Make Changes
+```bash
+# Edit code
+vim tree_sitter_analyzer/mcp/tools/analyze_scale_tool.py
+
+# Run tests
+pytest tests/ -v
+
+# Test CLI
+uv run python -m tree_sitter_analyzer examples/Sample.java --advanced --output-format=text
+```
+
+### 2. Test MCP Server
+```bash
+# Test server manually
+uv run python -m tree_sitter_analyzer.mcp.server
+
+# Should show server initialization logs
+```
+
+### 3. Test with Claude Desktop
+- Restart Claude Desktop
+- Test your changes through the AI assistant
+- Check logs for any issues
+
+## Debugging
+
+### Enable Debug Logging
+```bash
+export TREE_SITTER_ANALYZER_LOG_LEVEL=DEBUG
+uv run python -m tree_sitter_analyzer.mcp.server
+```
+
+### Common Issues
+
+**Import Errors:**
+```bash
+# Check dependencies
+uv run python -c "import tree_sitter_analyzer.mcp.server"
+```
+
+**Path Issues:**
+- Use absolute paths in MCP configuration
+- Verify project directory structure
+
+**MCP Protocol Issues:**
+- Check Claude Desktop logs
+- Verify MCP package version: `uv run python -c "import mcp; print(mcp.__version__)"`
+
+## Testing Changes
+
+### Unit Tests
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test
+pytest tests/test_mcp_tools.py -v
+
+# Run with coverage
+pytest tests/ --cov=tree_sitter_analyzer
+```
+
+### Integration Tests
+```bash
+# Test MCP tools
+uv run python -m pytest tests/test_mcp_integration.py -v
+```
+
+### Manual Testing
+```bash
+# Test CLI commands
+uv run python -m tree_sitter_analyzer examples/Sample.java --table=full
+
+# Test partial read
+uv run python -m tree_sitter_analyzer examples/Sample.java --partial-read --start-line 84 --end-line 86
+```
+
+## Contributing
+
+1. Create feature branch
+2. Make changes
+3. Run tests: `pytest tests/ -v`
+4. Test MCP integration
+5. Submit pull request
+
+## Need Help?
+
+- [GitHub Issues](https://github.com/aimasteracc/tree-sitter-analyzer/issues)
+- [User Setup Guide](MCP_SETUP_USERS.md) - For end users
+- [API Documentation](docs/api.md)

{tree_sitter_analyzer-0.8.0 → tree_sitter_analyzer-0.8.1}/MCP_SETUP_USERS.md

@@ -47,7 +47,7 @@ uv --version
 
 ### Add Configuration
 
-Open the config file and add this configuration:
+Open the config file and add this **recommended configuration**:
 
 ```json
 {
@@ -55,18 +55,61 @@ Open the config file and add this configuration:
     "tree-sitter-analyzer": {
       "command": "uv",
       "args": [
-        "run", 
-        "--with", 
+        "run",
+        "--with",
         "tree-sitter-analyzer[mcp]",
-        "python", 
-        "-m", 
+        "python",
+        "-m",
         "tree_sitter_analyzer.mcp.server"
+      ],
+      "env": {
+        "TREE_SITTER_PROJECT_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+> **💡 Why this configuration?**
+> - `${workspaceFolder}` automatically uses your current project directory
+> - Provides secure file access boundaries
+> - Works with any project without manual path changes
+> - Enables intelligent project root detection
+
+## Project Root Configuration
+
+The tree-sitter-analyzer automatically detects your project boundaries for security and functionality. Here's how it works:
+
+### ✅ Recommended: Use the configuration above
+The `${workspaceFolder}` setting automatically adapts to your current project directory. This works for:
+- VS Code workspaces
+- Any IDE that supports workspace variables
+- Most development environments
+
+### 🔧 Alternative: Fixed project path (for specific use cases)
+If you need to analyze files from a specific directory only:
+
+```json
+{
+  "mcpServers": {
+    "tree-sitter-analyzer": {
+      "command": "uv",
+      "args": [
+        "run", "--with", "tree-sitter-analyzer[mcp]",
+        "python", "-m", "tree_sitter_analyzer.mcp.server",
+        "--project-root", "/absolute/path/to/your/project"
       ]
     }
   }
 }
 ```
 
+### 🎯 What happens with project root?
+- **Security**: Only files within the project directory can be analyzed
+- **Smart detection**: Automatically finds project markers (.git, package.json, pyproject.toml, etc.)
+- **Path resolution**: Resolves relative paths correctly
+- **Performance**: Optimizes analysis for your project structure
+
 ## Step 3: Restart Claude Desktop
 
 Close and restart Claude Desktop completely.

{tree_sitter_analyzer-0.8.0 → tree_sitter_analyzer-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tree-sitter-analyzer
-Version: 0.8.0
+Version: 0.8.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
@@ -306,9 +306,32 @@ uv sync --extra all --extra mcp
 
 - **[MCP Setup Guide for Users](https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/MCP_SETUP_USERS.md)** - Simple setup for AI assistant users
 - **[MCP Setup Guide for Developers](https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/MCP_SETUP_DEVELOPERS.md)** - Local development configuration
+- **[Project Root Configuration](https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/PROJECT_ROOT_CONFIG.md)** - Complete configuration reference
 - **[API Documentation](https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/docs/api.md)** - Detailed API reference
 - **[Contributing Guide](https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/CONTRIBUTING.md)** - How to contribute
 
+### 🔒 Project Root Configuration
+
+Tree-sitter-analyzer automatically detects and secures your project boundaries:
+
+- **Auto-detection**: Finds project root from `.git`, `pyproject.toml`, `package.json`, etc.
+- **CLI**: Use `--project-root /path/to/project` for explicit control
+- **MCP**: Set `TREE_SITTER_PROJECT_ROOT=${workspaceFolder}` for workspace integration
+- **Security**: Only analyzes files within project boundaries
+
+**Recommended MCP configuration:**
+```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}"}
+    }
+  }
+}
+```
+
 ## 🧪 Testing
 
 This project maintains high code quality with **1126 passing tests**.

tree_sitter_analyzer-0.8.1/PROJECT_ROOT_CONFIG.md

@@ -0,0 +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)

{tree_sitter_analyzer-0.8.0 → tree_sitter_analyzer-0.8.1}/README.md

@@ -171,9 +171,32 @@ uv sync --extra all --extra mcp
 
 - **[MCP Setup Guide for Users](https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/MCP_SETUP_USERS.md)** - Simple setup for AI assistant users
 - **[MCP Setup Guide for Developers](https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/MCP_SETUP_DEVELOPERS.md)** - Local development configuration
+- **[Project Root Configuration](https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/PROJECT_ROOT_CONFIG.md)** - Complete configuration reference
 - **[API Documentation](https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/docs/api.md)** - Detailed API reference
 - **[Contributing Guide](https://github.com/aimasteracc/tree-sitter-analyzer/blob/main/CONTRIBUTING.md)** - How to contribute
 
+### 🔒 Project Root Configuration
+
+Tree-sitter-analyzer automatically detects and secures your project boundaries:
+
+- **Auto-detection**: Finds project root from `.git`, `pyproject.toml`, `package.json`, etc.
+- **CLI**: Use `--project-root /path/to/project` for explicit control
+- **MCP**: Set `TREE_SITTER_PROJECT_ROOT=${workspaceFolder}` for workspace integration
+- **Security**: Only analyzes files within project boundaries
+
+**Recommended MCP configuration:**
+```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}"}
+    }
+  }
+}
+```
+
 ## 🧪 Testing
 
 This project maintains high code quality with **1126 passing tests**.