cicada-mcp 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

cicada/utils/path_utils.py

@@ -124,6 +124,24 @@ def match_file_path(
     return bool(target_str.endswith(candidate_str))
 
 
+def is_git_repository(path: str | Path) -> bool:
+    """
+    Check if a path is a git repository.
+
+    Args:
+        path: Path to check
+
+    Returns:
+        True if the path is a git repository, False otherwise
+
+    Example:
+        is_git_repository('/repo') -> True
+        is_git_repository('/not/a/repo') -> False
+    """
+    git_dir = Path(path) / ".git"
+    return git_dir.exists()
+
+
 def find_repo_root(start_path: str | Path | None = None) -> Path | None:
     """
     Find the git repository root starting from a given path.

cicada/utils/text_utils.py

@@ -2,12 +2,63 @@
 Text utilities for identifier manipulation and processing.
 
 This module provides shared utilities for working with code identifiers,
-including splitting camelCase, PascalCase, and snake_case identifiers.
+including splitting camelCase, PascalCase, and snake_case identifiers,
+and extracting code-specific identifiers from text.
 """
 
 import re
 
 
+def extract_code_identifiers(text: str) -> tuple[list[str], list[str]]:
+    """
+    Extract code-specific identifiers and their split words from text.
+
+    Matches various identifier patterns: camelCase, PascalCase, snake_case,
+    and acronyms. Returns both the original identifiers and the individual
+    words extracted from those identifiers.
+
+    Args:
+        text: Input text to analyze
+
+    Returns:
+        Tuple of (identifiers, split_words) where:
+        - identifiers: original camelCase/PascalCase/snake_case identifiers
+        - split_words: individual words extracted from those identifiers
+
+    Examples:
+        >>> identifiers, split_words = extract_code_identifiers("getUserData and HTTPServer")
+        >>> "getUserData" in identifiers
+        True
+        >>> "get" in split_words
+        True
+    """
+    # Match camelCase, snake_case, PascalCase, and mixed patterns
+    patterns = [
+        r"\b[a-z]+[A-Z][a-zA-Z]*\b",  # camelCase (e.g., getUserData)
+        r"\b[A-Z]{2,}[a-z]+[a-zA-Z]*\b",  # Uppercase prefix + PascalCase
+        r"\b[A-Z][a-z]+[A-Z][a-zA-Z]*\b",  # PascalCase (e.g., UserController)
+        r"\b[a-z]+_[a-z_]+\b",  # snake_case (e.g., get_user_data)
+        r"\b[A-Z]{2,}\b",  # All UPPERCASE (e.g., HTTP, API)
+    ]
+
+    identifiers = []
+    for pattern in patterns:
+        matches = re.findall(pattern, text)
+        identifiers.extend(matches)
+
+    identifiers = list(set(identifiers))
+
+    # Split identifiers into individual words
+    split_words = []
+    for identifier in identifiers:
+        split_text = split_camel_snake_case(identifier)
+        # Extract individual words (lowercase, length > 1)
+        words = [word.lower() for word in split_text.split() if len(word) > 1 and word.isalpha()]
+        split_words.extend(words)
+
+    return identifiers, list(set(split_words))
+
+
 def split_identifier(identifier: str, lowercase: bool = True) -> list[str]:
     """
     Split an identifier by camelCase, PascalCase, and snake_case.

cicada/utils/tree_utils.py

@@ -0,0 +1,47 @@
+"""
+Tree-sitter utilities for extracting and analyzing tree nodes.
+
+This module provides shared utilities for working with tree-sitter parse trees,
+including extracting text from nodes and identifying function definitions.
+"""
+
+
+def extract_text_from_node(node, source_code: bytes) -> str:
+    """
+    Extract text from a tree-sitter node.
+
+    Args:
+        node: The tree-sitter node to extract text from
+        source_code: The source code bytes that the node was parsed from
+
+    Returns:
+        The decoded text content of the node
+
+    Examples:
+        >>> text = extract_text_from_node(node, source_code)
+        >>> text = extract_text_from_node(child_node, source_code)
+    """
+    return source_code[node.start_byte : node.end_byte].decode("utf-8")
+
+
+def is_function_definition_call(call_node, source_code: bytes) -> bool:
+    """
+    Check if a call node represents a function definition (def, defp, or defmodule).
+
+    Args:
+        call_node: A tree-sitter call node
+        source_code: The source code bytes that the node was parsed from
+
+    Returns:
+        True if the call is a function definition, False otherwise
+
+    Examples:
+        >>> if is_function_definition_call(node, source_code):
+        ...     skip_processing()
+    """
+    for child in call_node.children:
+        if child.type == "identifier":
+            target_text = extract_text_from_node(child, source_code)
+            if target_text in ["def", "defp", "defmodule"]:
+                return True
+    return False

cicada/version_check.py

@@ -7,6 +7,42 @@ Checks if a newer version of cicada is available on GitHub.
 import subprocess
 
 
+def get_git_tag() -> str | None:
+    """
+    Get the most recent git tag from build-time generated file.
+
+    Returns:
+        Git tag (e.g., "v0.2.0-rc1"), or None if not available
+    """
+    try:
+        from cicada._version_hash import GIT_TAG
+
+        if GIT_TAG and GIT_TAG != "unknown":
+            return GIT_TAG
+    except (ImportError, AttributeError):
+        pass
+
+    return None
+
+
+def get_git_commit_hash() -> str | None:
+    """
+    Get the current git commit hash from build-time generated file.
+
+    Returns:
+        Git commit hash (7-char short form), or None if not available
+    """
+    try:
+        from cicada._version_hash import GIT_HASH
+
+        if GIT_HASH and GIT_HASH != "unknown":
+            return GIT_HASH
+    except ImportError:
+        pass
+
+    return None
+
+
 def get_current_version() -> str:
     """
     Get the current version of cicada from pyproject.toml.
@@ -85,6 +121,69 @@ def compare_versions(current: str, latest: str) -> bool:
         return False
 
 
+def get_version_string() -> str:
+    """
+    Get a formatted version string including git tag and commit hash if available.
+
+    Returns:
+        Version string in format:
+        - "0.2.0" (no git info)
+        - "0.2.0 (v0.2.0-rc1/abc1234)" (with tag and hash)
+        - "0.2.0 (abc1234)" (hash only, no tag)
+    """
+    version = get_current_version()
+    git_tag = get_git_tag()
+    commit_hash = get_git_commit_hash()
+
+    # Build git info string
+    git_info_parts = []
+    if git_tag:
+        git_info_parts.append(git_tag)
+    if commit_hash:
+        git_info_parts.append(commit_hash)
+
+    if git_info_parts:
+        git_info = "/".join(git_info_parts)
+        return f"{version} ({git_info})"
+    return version
+
+
+def extract_version_tag(version_string: str) -> str:
+    """
+    Extract the pyproject version tag from a version string.
+
+    Args:
+        version_string: Version string like "0.2.2" or "0.2.2 (v0.2.2/0991325)"
+
+    Returns:
+        Just the version tag (e.g., "0.2.2")
+    """
+    # Split on space and take the first part (before any git info in parentheses)
+    return version_string.split()[0] if version_string else ""
+
+
+def version_mismatch(stored_version: str | None, current_version: str | None) -> bool:
+    """
+    Check if the stored version differs from the current version.
+
+    Only compares version tags (pyproject version), ignoring git tags and commit hashes.
+
+    Args:
+        stored_version: Version string from index.json metadata
+        current_version: Current cicada version string
+
+    Returns:
+        True if versions differ (or if stored_version is missing), False if they match
+    """
+    if not stored_version:
+        return True
+
+    stored_tag = extract_version_tag(stored_version)
+    current_tag = extract_version_tag(current_version or get_version_string())
+
+    return stored_tag != current_tag
+
+
 def check_for_updates() -> None:
     """
     Check if there's a newer version available on GitHub.

cicada/watch_manager.py

@@ -0,0 +1,320 @@
+"""
+Watch Process Manager - Manages a linked watch process for automatic reindexing.
+
+This module provides functionality to spawn and manage a watch process that runs
+alongside the MCP server, automatically reindexing when files change.
+"""
+
+import atexit
+import logging
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class WatchProcessManager:
+    """
+    Manages a linked watch process for automatic reindexing.
+
+    The watch process is spawned as a child process and is automatically
+    terminated when the parent process exits.
+    """
+
+    def __init__(
+        self,
+        repo_path: str | Path,
+        tier: str = "regular",
+        debounce: float = 2.0,
+        register_atexit: bool = True,
+    ):
+        """
+        Initialize the watch process manager.
+
+        Args:
+            repo_path: Path to the repository to watch
+            tier: Indexing tier (fast, regular, or max)
+            debounce: Debounce interval in seconds
+            register_atexit: Whether to register atexit cleanup handler (disable for testing)
+        """
+        self.repo_path = Path(repo_path).resolve()
+        self.tier = tier
+        self.debounce = debounce
+        self.process: subprocess.Popen[bytes] | None = None
+        self._cleanup_registered = False
+        self._register_atexit = register_atexit
+
+    def start(self) -> bool:
+        """
+        Start the watch process.
+
+        Returns:
+            True if the process was started successfully, False otherwise
+        """
+        if self.process is not None:
+            logger.warning("Watch process is already running")
+            return False
+
+        try:
+            # Build the command to run cicada watch
+            cmd = [
+                sys.executable,
+                "-m",
+                "cicada.cli",
+                "watch",
+                str(self.repo_path),
+                "--debounce",
+                str(self.debounce),
+            ]
+
+            # Add tier flag
+            if self.tier == "fast":
+                cmd.append("--fast")
+            elif self.tier == "max":
+                cmd.append("--max")
+            else:
+                cmd.append("--regular")
+
+            # Log to stderr so it doesn't interfere with MCP protocol
+            print(
+                f"Starting watch process for {self.repo_path} (tier={self.tier}, debounce={self.debounce}s)...",
+                file=sys.stderr,
+            )
+
+            # Start the watch process
+            # Use stdout=sys.stderr to redirect watch output to stderr
+            # This prevents it from interfering with the MCP protocol on stdout
+            self.process = subprocess.Popen(
+                cmd,
+                stdout=sys.stderr,
+                stderr=sys.stderr,
+                # Create new process group so it doesn't receive signals from parent's terminal
+                start_new_session=True,
+            )
+
+            # Verify the process actually started and didn't crash immediately
+            time.sleep(0.1)  # Brief delay to allow process to crash if it's going to
+            if self.process.poll() is not None:
+                print(
+                    f"Watch process exited immediately with code {self.process.returncode}",
+                    file=sys.stderr,
+                )
+                self.process = None
+                return False
+
+            # Register cleanup handler (unless disabled for testing)
+            if self._register_atexit and not self._cleanup_registered:
+                atexit.register(self._cleanup)
+                self._cleanup_registered = True
+
+            print(f"Watch process started (PID: {self.process.pid})", file=sys.stderr)
+            return True
+
+        except (FileNotFoundError, PermissionError, OSError) as e:
+            # Expected failures - bad config, permissions, or OS-level issues
+            logger.error(f"Cannot start watch process: {e}")
+            print(f"Error: Cannot start watch process: {e}", file=sys.stderr)
+            print("\nPossible causes:", file=sys.stderr)
+            print("  - Python interpreter not found", file=sys.stderr)
+            print("  - No execute permission", file=sys.stderr)
+            print("  - Repository path invalid", file=sys.stderr)
+            print("  - System resource issues", file=sys.stderr)
+            return False
+
+        except (ImportError, ModuleNotFoundError) as e:
+            # Module missing - installation problem
+            logger.error(f"Cicada module import failed: {e}")
+            print(f"Error: Cicada installation appears corrupted: {e}", file=sys.stderr)
+            print("Try reinstalling: uv tool install --force cicada-mcp", file=sys.stderr)
+            raise RuntimeError(f"Corrupted installation: {e}") from e
+
+        except (MemoryError, SystemError) as e:
+            # System-level failures - cannot recover
+            logger.critical(f"System error starting watch process: {e}")
+            print(f"CRITICAL: System error prevents watch process: {e}", file=sys.stderr)
+            raise RuntimeError(f"System failure: {e}") from e
+
+        except Exception as e:
+            # Unknown errors - log details and fail loudly
+            logger.exception("Unexpected error starting watch process")
+            print(f"ERROR: Unexpected failure starting watch process: {e}", file=sys.stderr)
+            raise RuntimeError(f"Unexpected error: {e}") from e
+
+    def stop(self) -> None:
+        """Stop the watch process gracefully."""
+        if self.process is None:
+            return
+
+        pid = self.process.pid  # Save PID before any cleanup
+        try:
+            print(f"Stopping watch process (PID: {pid})...", file=sys.stderr)
+
+            # Try graceful termination first (SIGTERM)
+            if self._terminate_process(signal.SIGTERM):
+                print("Watch process stopped gracefully", file=sys.stderr)
+            else:
+                # Force kill if graceful termination timed out (SIGKILL)
+                print("Watch process didn't stop gracefully, forcing...", file=sys.stderr)
+                self._terminate_process(signal.SIGKILL, force=True)
+                print("Watch process killed", file=sys.stderr)
+
+        except (ProcessLookupError, PermissionError) as e:
+            # Expected errors when process is already gone
+            logger.warning(f"Process {pid} already terminated: {e}")
+            print(f"Warning: Watch process {pid} already terminated", file=sys.stderr)
+            # Clear process reference since process is gone
+            self.process = None
+        except Exception as e:
+            # Unexpected errors - log with full context and warn user
+            logger.exception(f"Unexpected error stopping watch process {pid}")
+            print(f"ERROR: Failed to stop watch process {pid}: {e}", file=sys.stderr)
+            print(
+                "Warning: Process may still be running. Manual cleanup may be needed.",
+                file=sys.stderr,
+            )
+            raise  # Re-raise to propagate error
+        else:
+            # Only clear process reference if we successfully stopped it (no exceptions)
+            self.process = None
+
+    def _terminate_process(self, sig: signal.Signals, force: bool = False) -> bool:
+        """
+        Terminate the process using the specified signal.
+
+        This method handles platform differences (Unix vs Windows) and gracefully
+        falls back if process group operations aren't available or fail.
+
+        Args:
+            sig: Signal to send (SIGTERM for graceful, SIGKILL for force)
+            force: If True, waits indefinitely; if False, times out after 5 seconds
+
+        Returns:
+            True if process terminated successfully within timeout, False otherwise
+
+        Raises:
+            ValueError: If process is None
+        """
+        if self.process is None:
+            raise ValueError("Cannot terminate a None process")
+
+        # Send termination signal
+        if not self._send_termination_signal(sig):
+            return True  # Process already gone
+
+        # Wait for process to exit
+        if force:
+            # Force kill - wait without timeout
+            self.process.wait()
+            return True
+
+        # Graceful termination with timeout
+        try:
+            self.process.wait(timeout=5)
+            return True
+        except subprocess.TimeoutExpired:
+            return False
+
+    def _send_termination_signal(self, sig: signal.Signals) -> bool:
+        """Send termination signal to process.
+
+        Returns:
+            True if signal was sent, False if process already gone
+        """
+        assert self.process is not None, "Process should not be None"
+        try:
+            # Try process group termination on Unix-like systems
+            if hasattr(os, "killpg") and hasattr(os, "getpgid"):
+                try:
+                    os.killpg(os.getpgid(self.process.pid), sig)
+                except (ProcessLookupError, PermissionError, AttributeError):
+                    # Fall back to direct process termination
+                    self._send_direct_signal(sig)
+            else:
+                # Windows or platforms without killpg - use direct termination
+                self._send_direct_signal(sig)
+            return True
+        except (ProcessLookupError, PermissionError) as e:
+            # Process already gone or cannot signal - consider success
+            logger.info(f"Process {self.process.pid} termination: {e}")
+            return False
+
+    def _send_direct_signal(self, sig: signal.Signals) -> None:
+        """Send signal directly to process."""
+        assert self.process is not None, "Process should not be None"
+        if sig == signal.SIGTERM:
+            self.process.terminate()
+        else:
+            self.process.kill()
+
+    def _cleanup(self) -> None:
+        """Cleanup handler registered with atexit."""
+        try:
+            self.stop()
+        except Exception as e:
+            # Don't re-raise during atexit - just log the error and let process exit
+            logger.exception("Error during atexit cleanup")
+            print(f"Warning: Error stopping watch process during cleanup: {e}", file=sys.stderr)
+            # Don't re-raise - let process exit cleanly
+
+    def is_running(self) -> bool:
+        """
+        Check if the watch process is running.
+
+        Returns:
+            True if the process is running, False otherwise
+        """
+        if self.process is None:
+            return False
+
+        # Check if process is still running
+        return self.process.poll() is None
+
+
+# Global watch manager instance
+_watch_manager: WatchProcessManager | None = None
+
+
+def get_watch_manager() -> WatchProcessManager | None:
+    """Get the global watch manager instance."""
+    return _watch_manager
+
+
+def set_watch_manager(manager: WatchProcessManager | None) -> None:
+    """Set the global watch manager instance."""
+    global _watch_manager
+    _watch_manager = manager
+
+
+def start_watch_process(
+    repo_path: str | Path, tier: str = "regular", debounce: float = 2.0
+) -> bool:
+    """
+    Start a watch process for the given repository.
+
+    This is a convenience function that creates and starts a WatchProcessManager.
+
+    Args:
+        repo_path: Path to the repository to watch
+        tier: Indexing tier (fast, regular, or max)
+        debounce: Debounce interval in seconds
+
+    Returns:
+        True if started successfully, False otherwise
+    """
+    manager = WatchProcessManager(repo_path, tier, debounce)
+    if manager.start():
+        set_watch_manager(manager)
+        return True
+    return False
+
+
+def stop_watch_process() -> None:
+    """Stop the global watch process if running."""
+    manager = get_watch_manager()
+    if manager is not None:
+        manager.stop()
+        set_watch_manager(None)