tree-sitter-analyzer 1.6.1.2__py3-none-any.whl → 1.6.1.3__py3-none-any.whl

tree_sitter_analyzer/mcp/tools/output_format_validator.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+Output format parameter validation for search_content tool.
+
+Ensures mutual exclusion of output format parameters to prevent conflicts.
+"""
+
+import locale
+import os
+from typing import Any
+
+
+class OutputFormatValidator:
+    """Validator for output format parameters mutual exclusion."""
+
+    # Output format parameters that are mutually exclusive
+    OUTPUT_FORMAT_PARAMS = {
+        "total_only",
+        "count_only_matches",
+        "summary_only",
+        "group_by_file",
+        "optimize_paths"
+    }
+
+    # Token efficiency guidance for error messages
+    FORMAT_EFFICIENCY_GUIDE = {
+        "total_only": "~10 tokens (most efficient for count queries)",
+        "count_only_matches": "~50-200 tokens (file distribution analysis)",
+        "summary_only": "~500-2000 tokens (initial investigation)",
+        "group_by_file": "~2000-10000 tokens (context-aware review)",
+        "optimize_paths": "10-30% reduction (path compression)"
+    }
+
+    def _detect_language(self) -> str:
+        """Detect preferred language from environment."""
+        # Check environment variables for language preference
+        lang = os.environ.get('LANG', '')
+        if lang.startswith('ja'):
+            return 'ja'
+
+        # Check locale
+        try:
+            current_locale = locale.getlocale()[0]
+            if current_locale and current_locale.startswith('ja'):
+                return 'ja'
+        except Exception:
+            pass
+
+        # Default to English
+        return 'en'
+
+    def _get_error_message(self, specified_formats: list[str]) -> str:
+        """Generate localized error message with usage examples."""
+        lang = self._detect_language()
+        format_list = ", ".join(specified_formats)
+
+        if lang == 'ja':
+            # Japanese error message
+            base_message = (
+                f"⚠️ 出力形式パラメータエラー: 複数指定できません: {format_list}\n\n"
+                f"📋 排他的パラメータ: {', '.join(self.OUTPUT_FORMAT_PARAMS)}\n\n"
+                f"💡 効率性ガイド:\n"
+            )
+
+            for param, desc in self.FORMAT_EFFICIENCY_GUIDE.items():
+                base_message += f"  • {param}: {desc}\n"
+
+            base_message += (
+                "\n✅ 推奨パターン:\n"
+                "  • 件数確認: total_only=true\n"
+                "  • ファイル分布: count_only_matches=true\n"
+                "  • 初期調査: summary_only=true\n"
+                "  • 詳細レビュー: group_by_file=true\n"
+                "  • パス最適化: optimize_paths=true\n\n"
+                "❌ 間違った例: {\"total_only\": true, \"summary_only\": true}\n"
+                "✅ 正しい例: {\"total_only\": true}"
+            )
+        else:
+            # English error message
+            base_message = (
+                f"⚠️ Output Format Parameter Error: Multiple formats specified: {format_list}\n\n"
+                f"📋 Mutually Exclusive Parameters: {', '.join(self.OUTPUT_FORMAT_PARAMS)}\n\n"
+                f"💡 Token Efficiency Guide:\n"
+            )
+
+            for param, desc in self.FORMAT_EFFICIENCY_GUIDE.items():
+                base_message += f"  • {param}: {desc}\n"
+
+            base_message += (
+                "\n✅ Recommended Usage Patterns:\n"
+                "  • Count validation: total_only=true\n"
+                "  • File distribution: count_only_matches=true\n"
+                "  • Initial investigation: summary_only=true\n"
+                "  • Detailed review: group_by_file=true\n"
+                "  • Path optimization: optimize_paths=true\n\n"
+                "❌ Incorrect: {\"total_only\": true, \"summary_only\": true}\n"
+                "✅ Correct: {\"total_only\": true}"
+            )
+
+        return base_message
+
+    def validate_output_format_exclusion(self, arguments: dict[str, Any]) -> None:
+        """
+        Validate that only one output format parameter is specified.
+
+        Args:
+            arguments: Tool arguments dictionary
+
+        Raises:
+            ValueError: If multiple output format parameters are specified
+        """
+        specified_formats = []
+
+        for param in self.OUTPUT_FORMAT_PARAMS:
+            if arguments.get(param, False):
+                specified_formats.append(param)
+
+        if len(specified_formats) > 1:
+            error_message = self._get_error_message(specified_formats)
+            raise ValueError(error_message)
+
+    def get_active_format(self, arguments: dict[str, Any]) -> str:
+        """
+        Get the active output format from arguments.
+
+        Args:
+            arguments: Tool arguments dictionary
+
+        Returns:
+            Active format name or "normal" if none specified
+        """
+        for param in self.OUTPUT_FORMAT_PARAMS:
+            if arguments.get(param, False):
+                return param
+        return "normal"
+
+
+# Global validator instance
+_default_validator = None
+
+
+def get_default_validator() -> OutputFormatValidator:
+    """Get the default output format validator instance."""
+    global _default_validator
+    if _default_validator is None:
+        _default_validator = OutputFormatValidator()
+    return _default_validator

tree_sitter_analyzer/mcp/tools/search_content_tool.py

@@ -17,6 +17,7 @@ from ..utils.gitignore_detector import get_default_detector
 from ..utils.search_cache import get_default_cache
 from . import fd_rg_utils
 from .base_tool import BaseMCPTool
+from .output_format_validator import get_default_validator
 
 logger = logging.getLogger(__name__)
 
@@ -40,7 +41,26 @@ class SearchContentTool(BaseMCPTool):
     def get_tool_definition(self) -> dict[str, Any]:
         return {
             "name": "search_content",
-            "description": "Search text content inside files using ripgrep. Supports regex patterns, case sensitivity, context lines, and various output formats. Can search in directories or specific files.",
+            "description": """Search text content inside files using ripgrep. Supports regex patterns, case sensitivity, context lines, and various output formats. Can search in directories or specific files.
+
+⚠️ IMPORTANT: Token Efficiency Guide
+Choose output format parameters based on your needs to minimize token usage and maximize performance with efficient search strategies:
+
+🎯 RECOMMENDED WORKFLOW (Most Efficient Approach):
+1. START with total_only=true parameter for initial count validation (~10 tokens)
+2. IF more detail needed, use count_only_matches=true parameter for file distribution (~50-200 tokens)
+3. IF context needed, use summary_only=true parameter for overview (~500-2000 tokens)
+4. ONLY use full results when specific content review is required (~2000-50000+ tokens)
+
+💡 TOKEN EFFICIENCY COMPARISON:
+- total_only: ~10 tokens (single number) - MOST EFFICIENT for count queries
+- count_only_matches: ~50-200 tokens (file counts) - Good for file distribution analysis
+- summary_only: ~500-2000 tokens (condensed overview) - initial investigation
+- group_by_file: ~2000-10000 tokens (organized by file) - Context-aware review
+- optimize_paths: 10-30% reduction (path compression) - Use with deep directory structures
+- Full results: ~2000-50000+ tokens - Use sparingly for detailed analysis
+
+⚠️ MUTUALLY EXCLUSIVE: Only one output format parameter can be true at a time. Cannot be combined with other format parameters.""",
             "inputSchema": {
                 "type": "object",
                 "properties": {
@@ -131,27 +151,27 @@ class SearchContentTool(BaseMCPTool):
                     "count_only_matches": {
                         "type": "boolean",
                         "default": False,
-                        "description": "Return only match counts per file instead of full match details. Useful for statistics and performance",
+                        "description": "⚠️ EXCLUSIVE: Return only match counts per file (~50-200 tokens). RECOMMENDED for: File distribution analysis, understanding match spread across files. Cannot be combined with other output formats.",
                     },
                     "summary_only": {
                         "type": "boolean",
                         "default": False,
-                        "description": "Return a condensed summary of results to reduce context size. Shows top files and sample matches",
+                        "description": "⚠️ EXCLUSIVE: Return condensed overview with top files and sample matches (~500-2000 tokens). RECOMMENDED for: Initial investigation, scope confirmation, pattern validation. Cannot be combined with other output formats.",
                     },
                     "optimize_paths": {
                         "type": "boolean",
                         "default": False,
-                        "description": "Optimize file paths in results by removing common prefixes and shortening long paths. Saves tokens in output",
+                        "description": "⚠️ EXCLUSIVE: Optimize file paths by removing common prefixes (10-30% token reduction). RECOMMENDED for: Deep directory structures, large codebases. Cannot be combined with other output formats.",
                     },
                     "group_by_file": {
                         "type": "boolean",
                         "default": False,
-                        "description": "Group results by file to eliminate file path duplication when multiple matches exist in the same file. Significantly reduces tokens",
+                        "description": "⚠️ EXCLUSIVE: Group results by file, eliminating path duplication (~2000-10000 tokens). RECOMMENDED for: Context-aware review, analyzing matches within specific files. Cannot be combined with other output formats.",
                     },
                     "total_only": {
                         "type": "boolean",
                         "default": False,
-                        "description": "Return only the total match count as a number. Most token-efficient option for count queries. Takes priority over all other formats",
+                        "description": "⚠️ EXCLUSIVE: Return only total match count as single number (~10 tokens - MOST EFFICIENT). RECOMMENDED for: Count validation, filtering decisions, existence checks. Takes priority over all other formats. Cannot be combined with other output formats.",
                     },
                 },
                 "required": ["query"],
@@ -214,6 +234,9 @@ class SearchContentTool(BaseMCPTool):
             "no_ignore",
             "count_only_matches",
             "summary_only",
+            "total_only",
+            "group_by_file",
+            "optimize_paths",
         ]:
             if key in arguments and not isinstance(arguments[key], bool):
                 raise ValueError(f"{key} must be a boolean")
@@ -226,6 +249,10 @@ class SearchContentTool(BaseMCPTool):
                 if not isinstance(v, list) or not all(isinstance(x, str) for x in v):
                     raise ValueError(f"{key} must be an array of strings")
 
+        # Validate output format parameter exclusion
+        validator = get_default_validator()
+        validator.validate_output_format_exclusion(arguments)
+
         # Validate roots and files if provided
         if "roots" in arguments:
             self._validate_roots(arguments["roots"])
@@ -310,13 +337,19 @@ class SearchContentTool(BaseMCPTool):
                 if isinstance(cached_result, dict):
                     cached_result = cached_result.copy()
                     cached_result["cache_hit"] = True
-                return cached_result
+                    return cached_result
+                elif isinstance(cached_result, int):
+                    # Handle int results (for total_only)
+                    return cached_result
+                else:
+                    # Convert other types to dict format for type safety
+                    return {"success": True, "cache_hit": True, "value": cached_result}
 
         # Clamp counts to safety limits
         max_count = fd_rg_utils.clamp_int(
             arguments.get("max_count"),
             fd_rg_utils.DEFAULT_RESULTS_LIMIT,
-            fd_rg_utils.DEFAULT_RESULTS_LIMIT,
+            fd_rg_utils.MAX_RESULTS_HARD_CAP,
         )
         timeout_ms = arguments.get("timeout_ms")
 

tree_sitter_analyzer/mcp/utils/file_output_manager.py

@@ -8,6 +8,9 @@ appropriate extensions based on content type, with security validation.
 
 import json
 import os
+import tempfile
+import threading
+import time
 from pathlib import Path
 from typing import Any
 
@@ -22,6 +25,72 @@ class FileOutputManager:
     Manages file output for analysis results with automatic extension detection
     and security validation.
     """
+    
+    # クラス変数で警告メッセージの重複を防ぐ（プロセス内のみ）
+    _warning_messages_shown = set()
+    # スレッド間の排他制御用ロック
+    _warning_lock = threading.Lock()
+    
+    # プロセス間共有用のファイルベース重複防止
+    @staticmethod
+    def _get_warning_lock_file(warning_key: str) -> Path:
+        """警告メッセージ用のロックファイルパスを取得"""
+        temp_dir = Path(tempfile.gettempdir())
+        safe_key = warning_key.replace("/", "_").replace(":", "_").replace("\\", "_")
+        return temp_dir / f"tree_sitter_analyzer_warning_{safe_key}.lock"
+    
+    @staticmethod
+    def _should_show_warning(warning_key: str, max_age_seconds: int = 300) -> bool:
+        """
+        プロセス間で警告表示の可否を判定
+        
+        Args:
+            warning_key: 警告キー
+            max_age_seconds: ロックファイルの有効期間（秒）
+            
+        Returns:
+            警告を表示すべきかどうか
+        """
+        # スレッド間の排他制御
+        with FileOutputManager._warning_lock:
+            # プロセス内での重複チェック
+            if warning_key in FileOutputManager._warning_messages_shown:
+                return False
+            
+            # プロセス間での重複チェック
+            lock_file = FileOutputManager._get_warning_lock_file(warning_key)
+            
+            try:
+                # ロックファイルが存在し、有効期間内なら警告をスキップ
+                if lock_file.exists():
+                    mtime = lock_file.stat().st_mtime
+                    if time.time() - mtime < max_age_seconds:
+                        FileOutputManager._warning_messages_shown.add(warning_key)
+                        return False
+                    else:
+                        # 期限切れのロックファイルを削除
+                        try:
+                            lock_file.unlink()
+                        except (OSError, FileNotFoundError):
+                            pass
+                
+                # ロックファイルを排他的に作成して警告表示権を獲得
+                # 'x'モードは、ファイルが既に存在する場合FileExistsErrorを発生させる
+                try:
+                    with open(lock_file, 'x') as f:
+                        f.write(str(time.time()))
+                    FileOutputManager._warning_messages_shown.add(warning_key)
+                    return True
+                except FileExistsError:
+                    # 別のプロセスが先にロックを獲得した
+                    FileOutputManager._warning_messages_shown.add(warning_key)
+                    return False
+                
+            except (OSError, IOError):
+                # ファイル操作に失敗した場合はフォールバック
+                # プロセス内のみの重複防止に戻る
+                FileOutputManager._warning_messages_shown.add(warning_key)
+                return True
 
     def __init__(self, project_root: str | None = None):
         """
@@ -51,7 +120,11 @@ class FileOutputManager:
 
         # Priority 3: Current working directory as fallback
         self._output_path = str(Path.cwd())
-        logger.warning(f"Using current directory as output path: {self._output_path}")
+        
+        # プロセス間で重複警告を防ぐ
+        warning_key = f"fallback_path:{self._output_path}"
+        if self._should_show_warning(warning_key):
+            logger.warning(f"Using current directory as output path: {self._output_path}")
 
     def get_output_path(self) -> str:
         """

tree_sitter_analyzer/mcp/utils/search_cache.py

@@ -308,6 +308,15 @@ class SearchCache:
             "word": params.get("word", False),
             "multiline": params.get("multiline", False),
             "max_filesize": params.get("max_filesize", ""),
+            # Include output format parameters in cache key
+            "total_only": params.get("total_only", False),
+            "count_only_matches": params.get("count_only_matches", False),
+            "summary_only": params.get("summary_only", False),
+            "group_by_file": params.get("group_by_file", False),
+            "optimize_paths": params.get("optimize_paths", False),
+            "max_count": params.get("max_count", None),
+            "context_before": params.get("context_before", None),
+            "context_after": params.get("context_after", None),
         }
 
         # Create deterministic key

tree_sitter_analyzer/utils.py

@@ -14,191 +14,29 @@ from functools import wraps
 from pathlib import Path
 from typing import Any
 
+# Import the new unified logging manager
+from .logging_manager import get_logger_manager, SafeStreamHandler
+
 
-# Configure global logger
 def setup_logger(
     name: str = "tree_sitter_analyzer", level: int | str = logging.WARNING
 ) -> logging.Logger:
-    """Setup unified logger for the project"""
-    # Handle string level parameter
-    if isinstance(level, str):
-        level_upper = level.upper()
-        if level_upper == "DEBUG":
-            level = logging.DEBUG
-        elif level_upper == "INFO":
-            level = logging.INFO
-        elif level_upper == "WARNING":
-            level = logging.WARNING
-        elif level_upper == "ERROR":
-            level = logging.ERROR
-        else:
-            level = logging.WARNING  # Default fallback
-
-    # Get log level from environment variable (only if set and not empty)
-    env_level = os.environ.get("LOG_LEVEL", "").upper()
-    if env_level and env_level in ["DEBUG", "INFO", "WARNING", "ERROR"]:
-        if env_level == "DEBUG":
-            level = logging.DEBUG
-        elif env_level == "INFO":
-            level = logging.INFO
-        elif env_level == "WARNING":
-            level = logging.WARNING
-        elif env_level == "ERROR":
-            level = logging.ERROR
-    # If env_level is empty or not recognized, use the passed level parameter
-
-    logger = logging.getLogger(name)
-
-    # Clear existing handlers if this is a test logger to ensure clean state
-    if name.startswith("test_"):
-        logger.handlers.clear()
-
-    # Initialize file logging variables at function scope
-    enable_file_log = (
-        os.environ.get("TREE_SITTER_ANALYZER_ENABLE_FILE_LOG", "").lower() == "true"
-    )
-    file_log_level = level  # Default to main logger level
-
-    if not logger.handlers:  # Avoid duplicate handlers
-        # Create a safe handler that writes to stderr to avoid breaking MCP stdio
-        handler = SafeStreamHandler()
-        formatter = logging.Formatter(
-            "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-        )
-        handler.setFormatter(formatter)
-        logger.addHandler(handler)
-
-        # Optional file logging for debugging when launched by clients (e.g., Cursor)
-        # This helps diagnose cases where stdio is captured by the client and logs are hidden.
-        # Only enabled when TREE_SITTER_ANALYZER_ENABLE_FILE_LOG is set to 'true'
-        if enable_file_log:
-            try:
-                # Determine log directory
-                log_dir = os.environ.get("TREE_SITTER_ANALYZER_LOG_DIR")
-                if log_dir:
-                    # Use specified directory
-                    log_path = Path(log_dir) / "tree_sitter_analyzer.log"
-                    # Ensure directory exists
-                    Path(log_dir).mkdir(parents=True, exist_ok=True)
-                else:
-                    # Use system temporary directory
-                    temp_dir = tempfile.gettempdir()
-                    log_path = Path(temp_dir) / "tree_sitter_analyzer.log"
-
-                # Determine file log level
-                file_log_level_str = os.environ.get(
-                    "TREE_SITTER_ANALYZER_FILE_LOG_LEVEL", ""
-                ).upper()
-                if file_log_level_str and file_log_level_str in [
-                    "DEBUG",
-                    "INFO",
-                    "WARNING",
-                    "ERROR",
-                ]:
-                    if file_log_level_str == "DEBUG":
-                        file_log_level = logging.DEBUG
-                    elif file_log_level_str == "INFO":
-                        file_log_level = logging.INFO
-                    elif file_log_level_str == "WARNING":
-                        file_log_level = logging.WARNING
-                    elif file_log_level_str == "ERROR":
-                        file_log_level = logging.ERROR
-                else:
-                    # Use same level as main logger
-                    file_log_level = level
-
-                file_handler = logging.FileHandler(str(log_path), encoding="utf-8")
-                file_handler.setFormatter(formatter)
-                file_handler.setLevel(file_log_level)
-                logger.addHandler(file_handler)
-
-                # Log the file location for debugging purposes
-                if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
-                    try:
-                        sys.stderr.write(
-                            f"[logging_setup] File logging enabled: {log_path}\n"
-                        )
-                    except Exception:
-                        ...
-
-            except Exception as e:
-                # Never let logging configuration break runtime behavior; log to stderr if possible
-                if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
-                    try:
-                        sys.stderr.write(
-                            f"[logging_setup] file handler init skipped: {e}\n"
-                        )
-                    except Exception:
-                        ...
-
-    # Set the logger level to the minimum of main level and file log level
-    # This ensures that all messages that should go to any handler are processed
-    final_level = level
-    if enable_file_log:
-        # Use the minimum level to ensure all messages reach their intended handlers
-        final_level = min(level, file_log_level)
-
-    logger.setLevel(final_level)
-
-    # For test loggers, ensure they don't inherit from parent and force level
-    if logger.name.startswith("test_"):
-        logger.propagate = False
-        # Force the level setting for test loggers
-        logger.level = level
-
-    return logger
-
-
-class SafeStreamHandler(logging.StreamHandler):
     """
-    A StreamHandler that safely handles closed streams
+    Setup unified logger for the project using LoggerManager
+    
+    This function now delegates to the LoggerManager for unified logging
+    while maintaining backward compatibility with the existing API.
+    
+    Args:
+        name: Logger name
+        level: Log level (string or int)
+        
+    Returns:
+        Configured logger instance
     """
-
-    def __init__(self, stream=None):
-        # Default to sys.stderr to keep stdout clean for MCP stdio
-        super().__init__(stream if stream is not None else sys.stderr)
-
-    def emit(self, record: Any) -> None:
-        """
-        Emit a record, safely handling closed streams and pytest capture
-        """
-        try:
-            # Check if stream is closed before writing
-            if hasattr(self.stream, "closed") and self.stream.closed:
-                return
-
-            # Check if we can write to the stream
-            if not hasattr(self.stream, "write"):
-                return
-
-            # Special handling for pytest capture scenarios
-            # Check if this is a pytest capture stream that might be problematic
-            stream_name = getattr(self.stream, "name", "")
-            if stream_name is None or "pytest" in str(type(self.stream)).lower():
-                # For pytest streams, be extra cautious
-                try:
-                    # Just try to emit without any pre-checks
-                    super().emit(record)
-                    return
-                except (ValueError, OSError, AttributeError, UnicodeError):
-                    return
-
-            # Additional safety checks for stream validity for non-pytest streams
-            try:
-                # Test if we can actually write to the stream without flushing
-                # Avoid flush() as it can cause "I/O operation on closed file" in pytest
-                if hasattr(self.stream, "writable") and not self.stream.writable():
-                    return
-            except (ValueError, OSError, AttributeError, UnicodeError):
-                return
-
-            super().emit(record)
-        except (ValueError, OSError, AttributeError, UnicodeError):
-            # Silently ignore I/O errors during shutdown or pytest capture
-            pass
-        except Exception:
-            # For any other unexpected errors, silently ignore to prevent test failures
-            pass
+    # Use the unified logger manager
+    logger_manager = get_logger_manager()
+    return logger_manager.get_logger(name, level)
 
 
 def setup_safe_logging_shutdown() -> None:
@@ -369,17 +207,18 @@ def safe_print(message: str | None, level: str = "info", quiet: bool = False) ->
 
 
 def create_performance_logger(name: str) -> logging.Logger:
-    """Create performance-focused logger"""
-    perf_logger = logging.getLogger(f"{name}.performance")
-
-    if not perf_logger.handlers:
-        handler = SafeStreamHandler()
-        formatter = logging.Formatter("%(asctime)s - PERF - %(message)s")
-        handler.setFormatter(formatter)
-        perf_logger.addHandler(handler)
-        perf_logger.setLevel(logging.DEBUG)  # Change to DEBUG level
-
-    return perf_logger
+    """
+    Create performance-focused logger using unified LoggerManager
+    
+    Args:
+        name: Base name for the performance logger
+        
+    Returns:
+        Configured performance logger
+    """
+    logger_manager = get_logger_manager()
+    perf_logger_name = f"{name}.performance"
+    return logger_manager.get_logger(perf_logger_name, logging.DEBUG)
 
 
 # Performance logger instance
@@ -402,7 +241,7 @@ def log_performance(
             else:
                 detail_str = str(details)
             message += f" - {detail_str}"
-        perf_logger.debug(message)  # Change to DEBUG level
+        perf_logger.debug(message)
     except (ValueError, OSError) as e:
         if hasattr(sys, "stderr") and hasattr(sys.stderr, "write"):
             try:
@@ -412,18 +251,14 @@ def log_performance(
 
 
 def setup_performance_logger() -> logging.Logger:
-    """Set up performance logging"""
-    perf_logger = logging.getLogger("performance")
-
-    # Add handler if not already configured
-    if not perf_logger.handlers:
-        handler = SafeStreamHandler()
-        formatter = logging.Formatter("%(asctime)s - Performance - %(message)s")
-        handler.setFormatter(formatter)
-        perf_logger.addHandler(handler)
-        perf_logger.setLevel(logging.INFO)
-
-    return perf_logger
+    """
+    Set up performance logging (unified with create_performance_logger)
+    
+    Returns:
+        Performance logger instance
+    """
+    # Delegate to the unified create_performance_logger
+    return create_performance_logger("performance")
 
 
 class LoggingContext: