cicada-mcp 0.1.4__py3-none-any.whl

cicada/utils/call_site_formatter.py

@@ -0,0 +1,95 @@
+"""
+Call site formatting utilities.
+
+This module provides utilities for grouping and formatting call sites,
+eliminating duplication in the formatter module.
+"""
+
+from typing import Dict, List, Any, Tuple
+
+
+class CallSiteFormatter:
+    """
+    Formats and groups call sites for display.
+
+    This class consolidates the call site grouping and formatting logic
+    that appears multiple times in the formatter module.
+    """
+
+    @staticmethod
+    def group_by_caller(call_sites: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Group call sites by their caller (calling_module + calling_function).
+
+        When the same function is called multiple times from the same caller,
+        this consolidates those calls into a single entry with multiple line numbers.
+
+        Args:
+            call_sites: List of call site dictionaries with keys:
+                - calling_module: Module making the call
+                - calling_function: Function making the call (dict with name, arity)
+                - file: File path
+                - line: Line number
+                - code_line: Optional code snippet
+
+        Returns:
+            List of grouped call site dictionaries with keys:
+                - calling_module: Module making the call
+                - calling_function: Function making the call
+                - file: File path
+                - lines: List of line numbers (sorted)
+                - code_lines: List of {line, code} dicts (if present)
+
+        Example:
+            call_sites = [
+                {'calling_module': 'MyApp.User', 'calling_function': {'name': 'create', 'arity': 2},
+                 'file': 'lib/user.ex', 'line': 10},
+                {'calling_module': 'MyApp.User', 'calling_function': {'name': 'create', 'arity': 2},
+                 'file': 'lib/user.ex', 'line': 20},
+            ]
+            grouped = CallSiteFormatter.group_by_caller(call_sites)
+            # Returns:
+            # [{
+            #     'calling_module': 'MyApp.User',
+            #     'calling_function': {'name': 'create', 'arity': 2},
+            #     'file': 'lib/user.ex',
+            #     'lines': [10, 20]
+            # }]
+        """
+        grouped: Dict[Tuple, Dict[str, Any]] = {}
+
+        for site in call_sites:
+            # Create a key based on caller identity
+            calling_func = site.get("calling_function")
+            if calling_func:
+                key = (
+                    site["calling_module"],
+                    calling_func["name"],
+                    calling_func["arity"],
+                )
+            else:
+                key = (site["calling_module"], None, None)
+
+            if key not in grouped:
+                grouped[key] = {
+                    "calling_module": site["calling_module"],
+                    "calling_function": calling_func,
+                    "file": site["file"],
+                    "lines": [],
+                    "code_lines": [],
+                }
+
+            grouped[key]["lines"].append(site["line"])
+            if "code_line" in site:
+                grouped[key]["code_lines"].append(
+                    {"line": site["line"], "code": site["code_line"]}
+                )
+
+        # Convert back to list and sort lines
+        result = []
+        for data in grouped.values():
+            data["lines"].sort()
+            data["code_lines"].sort(key=lambda x: x["line"])
+            result.append(data)
+
+        return result

cicada/utils/function_grouper.py

@@ -0,0 +1,57 @@
+"""
+Function grouping utilities.
+
+This module provides utilities for grouping functions by name and arity,
+eliminating duplication across formatter and other modules.
+"""
+
+from typing import Dict, List, Any, Tuple
+
+
+class FunctionGrouper:
+    """
+    Groups functions by their name and arity.
+
+    This eliminates duplication of the grouping logic that appears
+    multiple times in the formatter module.
+    """
+
+    @staticmethod
+    def group_by_name_arity(
+        functions: List[Dict[str, Any]],
+    ) -> Dict[Tuple[str, int], List[Dict[str, Any]]]:
+        """
+        Group functions by their (name, arity) tuple.
+
+        Multiple function clauses with the same name and arity are grouped
+        together. This is common in Elixir where you can define multiple
+        clauses for the same function.
+
+        Args:
+            functions: List of function dictionaries with 'name' and 'arity' keys
+
+        Returns:
+            Dictionary mapping (name, arity) tuples to lists of function clauses
+
+        Example:
+            functions = [
+                {'name': 'create', 'arity': 1, 'line': 10},
+                {'name': 'create', 'arity': 1, 'line': 15},  # Second clause
+                {'name': 'create', 'arity': 2, 'line': 20},
+            ]
+            grouped = FunctionGrouper.group_by_name_arity(functions)
+            # Returns:
+            # {
+            #     ('create', 1): [{'name': 'create', 'arity': 1, ...}, {...}],
+            #     ('create', 2): [{'name': 'create', 'arity': 2, ...}]
+            # }
+        """
+        grouped: Dict[Tuple[str, int], List[Dict[str, Any]]] = {}
+
+        for func in functions:
+            key = (func["name"], func["arity"])
+            if key not in grouped:
+                grouped[key] = []
+            grouped[key].append(func)
+
+        return grouped

cicada/utils/hash_utils.py

@@ -0,0 +1,173 @@
+"""
+Utilities for computing and managing file hashes for incremental indexing.
+
+This module provides MD5-based file hashing to detect changes in the codebase
+and enable incremental reindexing, avoiding reprocessing of unchanged files.
+"""
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+
+def compute_file_hash(file_path: str) -> str:
+    """
+    Compute MD5 hash of a file's content.
+
+    Args:
+        file_path: Path to the file to hash
+
+    Returns:
+        MD5 hash as hexadecimal string
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        IOError: If file cannot be read
+    """
+    # Note: MD5 is used here for speed, not security. This is for content-based
+    # change detection, not cryptographic purposes. MD5 is significantly faster
+    # than SHA256 and collision risk is negligible for our use case.
+    hash_md5 = hashlib.md5()
+    try:
+        with open(file_path, "rb") as f:
+            # Read in chunks to handle large files efficiently
+            for chunk in iter(lambda: f.read(4096), b""):
+                hash_md5.update(chunk)
+        return hash_md5.hexdigest()
+    except FileNotFoundError:
+        raise FileNotFoundError(f"File not found: {file_path}")
+    except Exception as e:
+        raise IOError(f"Error reading file {file_path}: {e}")
+
+
+def load_file_hashes(cicada_dir: str) -> Dict[str, str]:
+    """
+    Load file hashes from .cicada/hashes.json.
+
+    Args:
+        cicada_dir: Path to the .cicada directory
+
+    Returns:
+        Dictionary mapping file paths to MD5 hashes.
+        Returns empty dict if hashes.json doesn't exist.
+    """
+    hashes_path = Path(cicada_dir) / "hashes.json"
+
+    if not hashes_path.exists():
+        return {}
+
+    try:
+        with open(hashes_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+            return data.get("hashes", {})
+    except (json.JSONDecodeError, IOError) as e:
+        print(f"Warning: Could not load hashes.json: {e}")
+        return {}
+
+
+def save_file_hashes(cicada_dir: str, hashes: Dict[str, str]) -> None:
+    """
+    Save file hashes to .cicada/hashes.json.
+
+    Args:
+        cicada_dir: Path to the .cicada directory
+        hashes: Dictionary mapping file paths to MD5 hashes
+    """
+    hashes_path = Path(cicada_dir) / "hashes.json"
+
+    # Ensure .cicada directory exists
+    os.makedirs(cicada_dir, exist_ok=True)
+
+    data = {
+        "version": "1.0",
+        "hashes": hashes,
+        "last_updated": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    }
+
+    try:
+        with open(hashes_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+    except IOError as e:
+        print(f"Warning: Could not save hashes.json: {e}")
+
+
+def detect_file_changes(
+    files: List[str], old_hashes: Dict[str, str], repo_path: str | None = None
+) -> Tuple[List[str], List[str], List[str]]:
+    """
+    Detect new, modified, and deleted files by comparing hashes.
+
+    Args:
+        files: List of current file paths (relative to repo root)
+        old_hashes: Dictionary of file paths to their previous MD5 hashes
+        repo_path: Optional repository root path. If provided, file paths
+                   will be resolved relative to this path.
+
+    Returns:
+        Tuple of (new_files, modified_files, deleted_files)
+        - new_files: Files that didn't exist in old_hashes
+        - modified_files: Files whose hash changed
+        - deleted_files: Files in old_hashes but not in current files list
+    """
+    new_files = []
+    modified_files = []
+
+    current_file_set = set(files)
+    old_file_set = set(old_hashes.keys())
+
+    # Detect deleted files
+    deleted_files = list(old_file_set - current_file_set)
+
+    # Detect new and modified files
+    for file_path in files:
+        # Resolve full path if repo_path provided
+        full_path = os.path.join(repo_path, file_path) if repo_path else file_path
+
+        if file_path not in old_hashes:
+            # New file
+            new_files.append(file_path)
+        else:
+            # Check if modified
+            # Note: Race condition possible if file modified between this check
+            # and actual indexing, but impact is minimal (re-detected next run)
+            try:
+                current_hash = compute_file_hash(full_path)
+                if current_hash != old_hashes[file_path]:
+                    modified_files.append(file_path)
+            except (FileNotFoundError, IOError) as e:
+                # File might have been deleted after listing
+                print(f"Warning: Could not hash {file_path}: {e}")
+                deleted_files.append(file_path)
+
+    return new_files, modified_files, deleted_files
+
+
+def compute_hashes_for_files(
+    files: List[str], repo_path: str | None = None
+) -> Dict[str, str]:
+    """
+    Compute MD5 hashes for a list of files.
+
+    Args:
+        files: List of file paths (relative to repo root)
+        repo_path: Optional repository root path. If provided, file paths
+                   will be resolved relative to this path.
+
+    Returns:
+        Dictionary mapping file paths to MD5 hashes
+    """
+    hashes = {}
+
+    for file_path in files:
+        # Resolve full path if repo_path provided
+        full_path = os.path.join(repo_path, file_path) if repo_path else file_path
+
+        try:
+            hashes[file_path] = compute_file_hash(full_path)
+        except (FileNotFoundError, IOError) as e:
+            print(f"Warning: Could not hash {file_path}: {e}")
+
+    return hashes

cicada/utils/index_utils.py

@@ -0,0 +1,290 @@
+"""
+Index file loading and saving utilities.
+
+This module provides centralized functions for loading and saving
+JSON index files with consistent error handling.
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any, Union
+
+
+def load_index(
+    index_path: Union[str, Path],
+    verbose: bool = False,
+    raise_on_error: bool = False,
+) -> Optional[Dict[str, Any]]:
+    """
+    Load a JSON index file.
+
+    Args:
+        index_path: Path to the index file
+        verbose: If True, print warning messages
+        raise_on_error: If True, raise exceptions instead of returning None
+
+    Returns:
+        Index dictionary, or None if file doesn't exist or can't be loaded
+
+    Raises:
+        FileNotFoundError: If raise_on_error=True and file doesn't exist
+        json.JSONDecodeError: If raise_on_error=True and JSON is invalid
+        IOError: If raise_on_error=True and file can't be read
+    """
+    index_file = Path(index_path)
+
+    if not index_file.exists():
+        if raise_on_error:
+            raise FileNotFoundError(f"Index file not found: {index_path}")
+        if verbose:
+            print(f"Warning: Index not found at {index_path}", file=sys.stderr)
+        return None
+
+    try:
+        with open(index_file, "r") as f:
+            return json.load(f)
+    except json.JSONDecodeError as e:
+        if raise_on_error:
+            raise
+        if verbose:
+            print(f"Warning: Could not parse index: {e}", file=sys.stderr)
+        return None
+    except IOError as e:
+        if raise_on_error:
+            raise
+        if verbose:
+            print(f"Warning: Could not read index: {e}", file=sys.stderr)
+        return None
+
+
+def save_index(
+    index: Dict[str, Any],
+    output_path: Union[str, Path],
+    indent: int = 2,
+    create_dirs: bool = True,
+    verbose: bool = False,
+) -> None:
+    """
+    Save an index dictionary to a JSON file.
+
+    Args:
+        index: Index dictionary to save
+        output_path: Path where the index will be saved
+        indent: JSON indentation (default: 2 spaces)
+        create_dirs: Create parent directories if they don't exist
+        verbose: If True, print confirmation message
+
+    Raises:
+        IOError: If file cannot be written
+        json.JSONEncodeError: If index cannot be serialized to JSON
+    """
+    output_file = Path(output_path)
+
+    if create_dirs:
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(output_file, "w") as f:
+        json.dump(index, f, indent=indent)
+
+    if verbose:
+        print(f"Index saved to: {output_path}")
+
+
+def validate_index_structure(
+    index: Any,
+    required_keys: Optional[list[str]] = None,
+) -> tuple[bool, Optional[str]]:
+    """
+    Validate the structure of an index dictionary.
+
+    Args:
+        index: Index dictionary to validate
+        required_keys: List of required top-level keys (default: ['modules', 'metadata'])
+
+    Returns:
+        Tuple of (is_valid, error_message)
+        error_message is None if index is valid
+
+    Example:
+        valid, error = validate_index_structure(index)
+        if not valid:
+            print(f"Invalid index: {error}")
+    """
+    if not isinstance(index, dict):
+        return False, "Index must be a dictionary"
+
+    if required_keys is None:
+        required_keys = ["modules", "metadata"]
+
+    for key in required_keys:
+        if key not in index:
+            return False, f"Missing required key: {key}"
+
+    # Validate modules structure
+    if "modules" in index and not isinstance(index["modules"], dict):
+        return False, "'modules' must be a dictionary"
+
+    # Validate metadata structure
+    if "metadata" in index and not isinstance(index["metadata"], dict):
+        return False, "'metadata' must be a dictionary"
+
+    return True, None
+
+
+def merge_indexes(
+    *indexes: Dict[str, Any],
+    strategy: str = "last_wins",
+) -> Dict[str, Any]:
+    """
+    Merge multiple index dictionaries.
+
+    Args:
+        *indexes: Variable number of index dictionaries to merge
+        strategy: Merge strategy ('last_wins' or 'first_wins')
+            - 'last_wins': Later indexes override earlier ones
+            - 'first_wins': Earlier indexes take precedence
+
+    Returns:
+        Merged index dictionary
+
+    Example:
+        merged = merge_indexes(index1, index2, index3, strategy='last_wins')
+    """
+    if not indexes:
+        return {}
+
+    # Start with empty structure
+    merged = {
+        "modules": {},
+        "metadata": {},
+    }
+
+    if strategy == "last_wins":
+        index_list = list(indexes)
+    elif strategy == "first_wins":
+        index_list = list(reversed(indexes))
+    else:
+        raise ValueError(f"Unknown merge strategy: {strategy}")
+
+    # Merge modules
+    for index in index_list:
+        if "modules" in index:
+            merged["modules"].update(index["modules"])
+
+    # Merge metadata (later ones override)
+    for index in index_list:
+        if "metadata" in index:
+            merged["metadata"].update(index["metadata"])
+
+    return merged
+
+
+def get_index_stats(index: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Get statistics about an index.
+
+    Args:
+        index: Index dictionary
+
+    Returns:
+        Dictionary with statistics:
+        - total_modules: Number of modules
+        - total_functions: Total function count
+        - public_functions: Public function count
+        - private_functions: Private function count
+
+    Example:
+        stats = get_index_stats(index)
+        print(f"Index contains {stats['total_modules']} modules")
+    """
+    stats = {
+        "total_modules": 0,
+        "total_functions": 0,
+        "public_functions": 0,
+        "private_functions": 0,
+    }
+
+    if "modules" not in index:
+        return stats
+
+    modules = index["modules"]
+    stats["total_modules"] = len(modules)
+
+    for module_data in modules.values():
+        if "functions" in module_data:
+            functions = module_data["functions"]
+            stats["total_functions"] += len(functions)
+
+            for func in functions:
+                if func.get("type") == "def":
+                    stats["public_functions"] += 1
+                elif func.get("type") == "defp":
+                    stats["private_functions"] += 1
+
+    return stats
+
+
+def merge_indexes_incremental(
+    old_index: Dict[str, Any],
+    new_index: Dict[str, Any],
+    deleted_files: list[str],
+) -> Dict[str, Any]:
+    """
+    Merge old and new indexes for incremental reindexing.
+
+    This specialized merge function:
+    1. Keeps all modules from old_index that aren't in deleted files
+    2. Adds/updates modules from new_index (new and modified files)
+    3. Removes modules whose files were deleted
+    4. Updates metadata with new counts and timestamp
+
+    Args:
+        old_index: Existing index dictionary
+        new_index: Index from newly processed files
+        deleted_files: List of file paths that were deleted
+
+    Returns:
+        Merged index dictionary with updated modules and metadata
+
+    Example:
+        merged = merge_indexes_incremental(
+            old_index=existing_index,
+            new_index=changed_files_index,
+            deleted_files=['lib/deleted.ex']
+        )
+    """
+    # Start with empty structure
+    merged = {
+        "modules": {},
+        "metadata": {},
+    }
+
+    # Convert deleted files list to set for O(1) lookup
+    deleted_set = set(deleted_files)
+
+    # Keep modules from old_index that aren't deleted
+    if "modules" in old_index:
+        for module_name, module_data in old_index["modules"].items():
+            file_path = module_data.get("file", "")
+            if file_path not in deleted_set:
+                merged["modules"][module_name] = module_data
+
+    # Add/update modules from new_index (overrides old ones with same name)
+    if "modules" in new_index:
+        merged["modules"].update(new_index["modules"])
+
+    # Merge metadata - take from new_index if available, else old_index
+    if "metadata" in new_index:
+        merged["metadata"].update(new_index["metadata"])
+    elif "metadata" in old_index:
+        merged["metadata"].update(old_index["metadata"])
+
+    # Update module and function counts
+    stats = get_index_stats(merged)
+    merged["metadata"]["total_modules"] = stats["total_modules"]
+    merged["metadata"]["total_functions"] = stats["total_functions"]
+    merged["metadata"]["public_functions"] = stats["public_functions"]
+    merged["metadata"]["private_functions"] = stats["private_functions"]
+
+    return merged