cicada-mcp 0.1.4__py3-none-any.whl

cicada/utils/path_utils.py

@@ -0,0 +1,240 @@
+"""
+Path manipulation utilities.
+
+This module provides centralized path normalization and resolution
+functions used throughout the codebase.
+"""
+
+from pathlib import Path
+from typing import Optional, Union
+
+
+def normalize_file_path(
+    file_path: Union[str, Path],
+    strip_leading_dot: bool = True,
+    strip_trailing_whitespace: bool = True,
+) -> str:
+    """
+    Normalize a file path for consistent comparisons.
+
+    Args:
+        file_path: Path to normalize
+        strip_leading_dot: Remove leading './' if present
+        strip_trailing_whitespace: Remove trailing whitespace
+
+    Returns:
+        Normalized path string
+
+    Example:
+        normalize_file_path('./lib/user.ex') -> 'lib/user.ex'
+        normalize_file_path('  lib/user.ex  ') -> 'lib/user.ex'
+    """
+    path_str = str(file_path)
+
+    if strip_trailing_whitespace:
+        path_str = path_str.strip()
+
+    if strip_leading_dot:
+        # Remove leading './' prefix (not individual '.' or '/' characters)
+        while path_str.startswith("./"):
+            path_str = path_str[2:]
+
+    return path_str
+
+
+def resolve_to_repo_root(
+    file_path: Union[str, Path],
+    repo_root: Union[str, Path],
+) -> Path:
+    """
+    Resolve a file path relative to repository root.
+
+    Handles both absolute and relative paths, converting absolute paths
+    to be relative to the repository root.
+
+    Args:
+        file_path: Path to resolve (can be absolute or relative)
+        repo_root: Repository root directory
+
+    Returns:
+        Path relative to repo root
+
+    Raises:
+        ValueError: If absolute path is not within repo root
+
+    Example:
+        resolve_to_repo_root('/repo/lib/user.ex', '/repo') -> Path('lib/user.ex')
+        resolve_to_repo_root('lib/user.ex', '/repo') -> Path('lib/user.ex')
+    """
+    file_path_obj = Path(file_path)
+    repo_root_obj = Path(repo_root).resolve()
+
+    # If already relative, return as-is
+    if not file_path_obj.is_absolute():
+        return file_path_obj
+
+    # Convert absolute to relative
+    try:
+        return file_path_obj.relative_to(repo_root_obj)
+    except ValueError:
+        raise ValueError(f"File path {file_path} is not within repository {repo_root}")
+
+
+def match_file_path(
+    candidate: Union[str, Path],
+    target: Union[str, Path],
+    normalize: bool = True,
+) -> bool:
+    """
+    Check if two file paths match, with flexible matching rules.
+
+    Supports:
+    - Exact match
+    - Candidate ends with target
+    - Target ends with candidate
+
+    Args:
+        candidate: File path to check
+        target: Target file path
+        normalize: Whether to normalize paths before comparison
+
+    Returns:
+        True if paths match
+
+    Example:
+        match_file_path('lib/user.ex', 'lib/user.ex') -> True
+        match_file_path('/repo/lib/user.ex', 'lib/user.ex') -> True
+        match_file_path('user.ex', 'lib/user.ex') -> True
+    """
+    if normalize:
+        candidate_str = normalize_file_path(candidate)
+        target_str = normalize_file_path(target)
+    else:
+        candidate_str = str(candidate)
+        target_str = str(target)
+
+    # Exact match
+    if candidate_str == target_str:
+        return True
+
+    # Candidate ends with target (absolute path provided, target is relative)
+    if candidate_str.endswith(target_str):
+        return True
+
+    # Target ends with candidate (partial path provided)
+    if target_str.endswith(candidate_str):
+        return True
+
+    return False
+
+
+def find_repo_root(start_path: Optional[Union[str, Path]] = None) -> Optional[Path]:
+    """
+    Find the git repository root starting from a given path.
+
+    Args:
+        start_path: Path to start searching from (default: current directory)
+
+    Returns:
+        Path to repository root, or None if not in a git repo
+
+    Example:
+        find_repo_root('/repo/lib/user') -> Path('/repo')
+        find_repo_root('/not/a/repo') -> None
+    """
+    if start_path is None:
+        current = Path.cwd()
+    else:
+        current = Path(start_path).resolve()
+
+    # Walk up the directory tree looking for .git
+    for parent in [current] + list(current.parents):
+        if (parent / ".git").exists():
+            return parent
+
+    return None
+
+
+def ensure_relative_to_repo(
+    file_path: Union[str, Path],
+    repo_root: Union[str, Path],
+) -> str:
+    """
+    Ensure a file path is relative to the repository root.
+
+    This is a convenience function that combines normalization and
+    resolution. If the path is already relative, it's normalized.
+    If it's absolute, it's converted to relative.
+
+    Args:
+        file_path: File path to process
+        repo_root: Repository root directory
+
+    Returns:
+        Normalized path string relative to repo root
+
+    Example:
+        ensure_relative_to_repo('/repo/./lib/user.ex', '/repo') -> 'lib/user.ex'
+        ensure_relative_to_repo('lib/user.ex', '/repo') -> 'lib/user.ex'
+    """
+    resolved = resolve_to_repo_root(file_path, repo_root)
+    return normalize_file_path(resolved)
+
+
+def ensure_gitignore_has_cicada(repo_root: Union[str, Path]) -> bool:
+    """
+    Ensure .gitignore contains .cicada/ directory entry.
+
+    If .gitignore exists and doesn't already contain .cicada/, adds it.
+    If .gitignore doesn't exist, this function does nothing.
+
+    Args:
+        repo_root: Repository root directory
+
+    Returns:
+        True if .cicada/ was added to .gitignore, False otherwise
+
+    Example:
+        ensure_gitignore_has_cicada('/repo') -> True (if added)
+        ensure_gitignore_has_cicada('/repo') -> False (if already present or no .gitignore)
+    """
+    repo_root_path = Path(repo_root).resolve()
+    gitignore_path = repo_root_path / ".gitignore"
+
+    # Do nothing if .gitignore doesn't exist
+    if not gitignore_path.exists():
+        return False
+
+    try:
+        # Read existing .gitignore
+        with open(gitignore_path, "r") as f:
+            content = f.read()
+
+        # Check if .cicada/ is already present in actual gitignore patterns
+        # (ignore comment lines starting with #)
+        for line in content.splitlines():
+            # Strip whitespace and skip empty lines and comments
+            stripped = line.strip()
+            if stripped and not stripped.startswith("#"):
+                # Check if this line contains .cicada as a gitignore pattern
+                # Valid patterns: .cicada, .cicada/, /.cicada, /.cicada/, **/.cicada/, etc.
+                if (
+                    stripped in (".cicada", ".cicada/")
+                    or stripped.endswith("/.cicada")
+                    or stripped.endswith("/.cicada/")
+                ):
+                    return False
+
+        # Add .cicada/ to .gitignore
+        with open(gitignore_path, "a") as f:
+            # Add newline if file doesn't end with one
+            if content and not content.endswith("\n"):
+                f.write("\n")
+
+            f.write(".cicada/\n")
+
+        return True
+
+    except (IOError, OSError):
+        # Fail silently if we can't read/write the file
+        return False

cicada/utils/signature_builder.py

@@ -0,0 +1,106 @@
+"""
+Function signature building utilities.
+
+This module provides utilities for formatting function signatures,
+eliminating duplication across the formatter module.
+"""
+
+from typing import Dict, List, Any
+
+
+class SignatureBuilder:
+    """
+    Builds formatted function signatures from function data.
+
+    This class consolidates signature formatting logic that appears
+    in multiple places in the formatter module.
+    """
+
+    @staticmethod
+    def build(func: Dict[str, Any]) -> str:
+        """
+        Build a formatted function signature.
+
+        Creates signatures like:
+        - "func_name(arg1: type1, arg2: type2) :: return_type"
+        - "func_name(arg1, arg2)"
+        - "func_name/2"
+
+        Args:
+            func: Function dictionary with keys:
+                - name: Function name
+                - arity: Function arity
+                - args: Optional list of argument names
+                - args_with_types: Optional list of {name, type} dicts
+                - return_type: Optional return type string
+
+        Returns:
+            Formatted signature string
+
+        Example:
+            func = {
+                'name': 'create_user',
+                'arity': 2,
+                'args_with_types': [
+                    {'name': 'attrs', 'type': 'map'},
+                    {'name': 'opts', 'type': 'keyword'}
+                ],
+                'return_type': '{:ok, User.t()} | {:error, Ecto.Changeset.t()}'
+            }
+            sig = SignatureBuilder.build(func)
+            # Returns: "create_user(attrs: map, opts: keyword) :: {:ok, User.t()} | {:error, Ecto.Changeset.t()}"
+        """
+        func_name = func["name"]
+        signature = ""
+
+        # If we have args_with_types, use that for rich signatures
+        if "args_with_types" in func and func["args_with_types"]:
+            args_str = SignatureBuilder._format_args_with_types(func["args_with_types"])
+            signature = f"{func_name}({args_str})"
+
+        # Otherwise, fallback to args without types
+        elif "args" in func and func["args"]:
+            args_str = ", ".join(func["args"])
+            signature = f"{func_name}({args_str})"
+
+        # No args, just show function name with empty parens or /0
+        elif func["arity"] == 0:
+            signature = f"{func_name}()"
+
+        # Fallback to name/arity notation
+        else:
+            signature = f"{func_name}/{func['arity']}"
+
+        # Append return type if available
+        if "return_type" in func and func["return_type"]:
+            signature += f" :: {func['return_type']}"
+
+        return signature
+
+    @staticmethod
+    def _format_args_with_types(args_with_types: List[Dict[str, str]]) -> str:
+        """
+        Format arguments with type annotations.
+
+        Args:
+            args_with_types: List of dicts with 'name' and 'type' keys
+
+        Returns:
+            Comma-separated string of "name: type" pairs
+
+        Example:
+            args = [
+                {'name': 'attrs', 'type': 'map'},
+                {'name': 'opts', 'type': 'keyword'}
+            ]
+            formatted = SignatureBuilder._format_args_with_types(args)
+            # Returns: "attrs: map, opts: keyword"
+        """
+        formatted_args: list[str] = []
+        for arg in args_with_types:
+            if arg.get("type"):
+                formatted_args.append(f"{arg['name']}: {arg['type']}")
+            else:
+                formatted_args.append(arg["name"])
+
+        return ", ".join(formatted_args)

cicada/utils/storage.py

@@ -0,0 +1,111 @@
+"""
+Storage management utilities for Cicada.
+
+Handles creation and management of storage directories for index files.
+"""
+
+import hashlib
+from pathlib import Path
+
+
+def get_repo_hash(repo_path: str | Path) -> str:
+    """
+    Generate a unique hash for a repository path.
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        Hex string hash of the repository path
+    """
+    repo_path_str = str(Path(repo_path).resolve())
+    return hashlib.sha256(repo_path_str.encode()).hexdigest()[:16]
+
+
+def get_storage_dir(repo_path: str | Path) -> Path:
+    """
+    Get the storage directory for a repository.
+
+    Storage structure:
+        ~/.cicada/projects/<repo_hash>/
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        Path to the storage directory for this repository
+    """
+    repo_hash = get_repo_hash(repo_path)
+    storage_dir = Path.home() / ".cicada" / "projects" / repo_hash
+    return storage_dir
+
+
+def create_storage_dir(repo_path: str | Path) -> Path:
+    """
+    Create the storage directory for a repository if it doesn't exist.
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        Path to the created storage directory
+    """
+    storage_dir = get_storage_dir(repo_path)
+    storage_dir.mkdir(parents=True, exist_ok=True)
+    return storage_dir
+
+
+def get_index_path(repo_path: str | Path) -> Path:
+    """
+    Get the path to the index file for a repository.
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        Path to the index.json file
+    """
+    storage_dir = get_storage_dir(repo_path)
+    return storage_dir / "index.json"
+
+
+def get_config_path(repo_path: str | Path) -> Path:
+    """
+    Get the path to the config file for a repository.
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        Path to the config.yaml file
+    """
+    storage_dir = get_storage_dir(repo_path)
+    return storage_dir / "config.yaml"
+
+
+def get_hashes_path(repo_path: str | Path) -> Path:
+    """
+    Get the path to the hashes file for a repository.
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        Path to the hashes.json file
+    """
+    storage_dir = get_storage_dir(repo_path)
+    return storage_dir / "hashes.json"
+
+
+def get_pr_index_path(repo_path: str | Path) -> Path:
+    """
+    Get the path to the PR index file for a repository.
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        Path to the pr_index.json file
+    """
+    storage_dir = get_storage_dir(repo_path)
+    return storage_dir / "pr_index.json"

cicada/utils/subprocess_runner.py

@@ -0,0 +1,182 @@
+"""
+Subprocess execution utilities.
+
+This module provides centralized subprocess execution with consistent
+error handling and logging patterns.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional, List, Union
+
+
+class SubprocessRunner:
+    """
+    Centralized subprocess execution with error handling.
+
+    This class provides consistent subprocess execution patterns used
+    throughout the codebase, reducing duplication and ensuring uniform
+    error handling.
+    """
+
+    def __init__(self, cwd: Optional[Union[str, Path]] = None, verbose: bool = False):
+        """
+        Initialize the subprocess runner.
+
+        Args:
+            cwd: Working directory for commands (default: current directory)
+            verbose: If True, print command output to stderr
+        """
+        self.cwd = Path(cwd) if cwd else None
+        self.verbose = verbose
+
+    def run(
+        self,
+        cmd: Union[str, List[str]],
+        capture_output: bool = True,
+        text: bool = True,
+        check: bool = True,
+        timeout: Optional[int] = None,
+    ) -> subprocess.CompletedProcess:
+        """
+        Run a subprocess command with error handling.
+
+        Args:
+            cmd: Command to execute (string or list)
+            capture_output: Whether to capture stdout/stderr
+            text: Whether to return output as text (vs bytes)
+            check: Whether to raise exception on non-zero exit
+            timeout: Optional timeout in seconds
+
+        Returns:
+            CompletedProcess instance
+
+        Raises:
+            subprocess.CalledProcessError: If command fails and check=True
+            subprocess.TimeoutExpired: If timeout is reached
+        """
+        try:
+            result = subprocess.run(
+                cmd,
+                cwd=self.cwd,
+                capture_output=capture_output,
+                text=text,
+                check=check,
+                timeout=timeout,
+            )
+
+            if self.verbose and result.stdout:
+                print(result.stdout, file=sys.stderr)
+
+            return result
+
+        except subprocess.CalledProcessError as e:
+            if self.verbose:
+                print(f"Command failed: {cmd}", file=sys.stderr)
+                if e.stderr:
+                    print(f"Error: {e.stderr}", file=sys.stderr)
+            raise
+        except subprocess.TimeoutExpired as e:
+            if self.verbose:
+                print(f"Command timed out: {cmd}", file=sys.stderr)
+            raise
+
+    def run_git_command(
+        self,
+        args: Union[str, List[str]],
+        check: bool = True,
+    ) -> subprocess.CompletedProcess:
+        """
+        Run a git command with consistent error handling.
+
+        Args:
+            args: Git command arguments (without 'git')
+            check: Whether to raise exception on non-zero exit
+
+        Returns:
+            CompletedProcess instance
+
+        Example:
+            runner.run_git_command(['status', '--short'])
+            runner.run_git_command('log --oneline -n 5')
+        """
+        if isinstance(args, str):
+            cmd = f"git {args}"
+        else:
+            cmd = ["git"] + args
+
+        return self.run(cmd, check=check)
+
+    def run_gh_command(
+        self,
+        args: Union[str, List[str]],
+        check: bool = True,
+    ) -> subprocess.CompletedProcess:
+        """
+        Run a GitHub CLI command with consistent error handling.
+
+        Args:
+            args: gh command arguments (without 'gh')
+            check: Whether to raise exception on non-zero exit
+
+        Returns:
+            CompletedProcess instance
+
+        Example:
+            runner.run_gh_command(['pr', 'list'])
+            runner.run_gh_command('api repos/owner/repo/pulls')
+        """
+        if isinstance(args, str):
+            cmd = f"gh {args}"
+        else:
+            cmd = ["gh"] + args
+
+        return self.run(cmd, check=check)
+
+
+# Convenience functions for simple use cases
+
+
+def run_git_command(
+    args: Union[str, List[str]],
+    cwd: Optional[Union[str, Path]] = None,
+    check: bool = True,
+    verbose: bool = False,
+) -> subprocess.CompletedProcess:
+    """
+    Run a git command (convenience function).
+
+    Args:
+        args: Git command arguments (without 'git')
+        cwd: Working directory
+        check: Whether to raise exception on non-zero exit
+        verbose: Whether to print output
+
+    Returns:
+        CompletedProcess instance
+    """
+    runner = SubprocessRunner(cwd=cwd, verbose=verbose)
+    return runner.run_git_command(args, check=check)
+
+
+def run_gh_command(
+    args: Union[str, List[str]],
+    cwd: Optional[Union[str, Path]] = None,
+    check: bool = True,
+    verbose: bool = False,
+) -> subprocess.CompletedProcess:
+    """
+    Run a GitHub CLI command (convenience function).
+
+    Args:
+        args: gh command arguments (without 'gh')
+        cwd: Working directory
+        check: Whether to raise exception on non-zero exit
+        verbose: Whether to print output
+
+    Returns:
+        CompletedProcess instance
+    """
+    runner = SubprocessRunner(cwd=cwd, verbose=verbose)
+    return runner.run_gh_command(args, check=check)