cicada-mcp 0.1.4__py3-none-any.whl

cicada/dead_code_analyzer.py

@@ -0,0 +1,282 @@
+"""
+Dead Code Analyzer for Elixir codebases.
+
+Identifies potentially unused public functions using the indexed codebase data.
+
+Author: Cursor(Auto)
+"""
+
+from typing import Dict, List, Optional
+
+
+class DeadCodeAnalyzer:
+    """Analyzes Elixir code index to find potentially unused public functions."""
+
+    def __init__(self, index: dict):
+        """
+        Initialize analyzer with code index.
+
+        Args:
+            index: The indexed codebase data containing modules and their metadata
+        """
+        self.index = index
+        self.modules = index.get("modules", {})
+
+    def analyze(self) -> dict:
+        """
+        Analyze the index to find dead code candidates.
+
+        Returns:
+            Dict with analysis results:
+            {
+                "summary": {
+                    "total_public_functions": int,
+                    "analyzed_functions": int,
+                    "skipped_impl_functions": int,
+                    "skipped_test_functions": int,
+                    "total_candidates": int
+                },
+                "candidates": {
+                    "high": [...],
+                    "medium": [...],
+                    "low": [...]
+                }
+            }
+        """
+        # Track statistics
+        total_public = 0
+        skipped_impl = 0
+        skipped_files = 0  # test files and .exs files
+        analyzed = 0
+
+        # Collect candidates by confidence level
+        candidates = {"high": [], "medium": [], "low": []}
+
+        # Analyze each module
+        for module_name, module_data in self.modules.items():
+            # Skip test files and .exs files entirely
+            if self._is_test_file(module_data["file"]):
+                skipped_files += sum(
+                    1 for f in module_data["functions"] if f["type"] == "def"
+                )
+                continue
+
+            # Analyze each function in the module
+            for function in module_data["functions"]:
+                # Only analyze public functions
+                if function["type"] != "def":
+                    continue
+
+                total_public += 1
+
+                # Skip functions with @impl (they're called by behaviors)
+                if function.get("impl"):
+                    skipped_impl += 1
+                    continue
+
+                analyzed += 1
+
+                # Find usages of this function
+                usage_count = self._find_usages(
+                    module_name, function["name"], function["arity"]
+                )
+
+                # If function is used, skip it
+                if usage_count > 0:
+                    continue
+
+                # Function has zero usages - determine confidence level
+                confidence = self._calculate_confidence(module_name, module_data)
+
+                # Create candidate entry
+                candidate = {
+                    "module": module_name,
+                    "function": function["name"],
+                    "arity": function["arity"],
+                    "line": function["line"],
+                    "file": module_data["file"],
+                    "signature": function.get(
+                        "signature", f"{function['type']} {function['name']}"
+                    ),
+                }
+
+                # Add context for low/medium confidence
+                if confidence == "low":
+                    # Module is used as value somewhere
+                    value_mentioners = self._find_value_mentioners(module_name)
+                    candidate["reason"] = "module_passed_as_value"
+                    candidate["mentioned_in"] = value_mentioners
+                elif confidence == "medium":
+                    # Module has behaviors or uses
+                    candidate["reason"] = "module_has_behaviors_or_uses"
+                    candidate["uses"] = module_data.get("uses", [])
+                    candidate["behaviours"] = module_data.get("behaviours", [])
+                else:
+                    candidate["reason"] = "no_usage_found"
+
+                candidates[confidence].append(candidate)
+
+        # Build summary
+        total_candidates = sum(len(candidates[level]) for level in candidates)
+
+        return {
+            "summary": {
+                "total_public_functions": total_public,
+                "analyzed": analyzed,
+                "skipped_impl": skipped_impl,
+                "skipped_files": skipped_files,
+                "total_candidates": total_candidates,
+            },
+            "candidates": candidates,
+        }
+
+    def _is_test_file(self, file_path: str) -> bool:
+        """
+        Check if a file should be skipped from dead code analysis.
+
+        Files are skipped if they are:
+        - Test files (in 'test/' directory or '_test.ex' suffix)
+        - Script files (.exs extension)
+
+        Args:
+            file_path: Path to the file
+
+        Returns:
+            True if the file should be skipped
+        """
+        file_lower = file_path.lower()
+        return (
+            # Test files
+            "/test/" in file_lower
+            or file_lower.startswith("test/")
+            or file_lower.endswith("_test.ex")
+            # All .exs files (scripts, config files, etc.)
+            or file_lower.endswith(".exs")
+        )
+
+    def _find_usages(
+        self, target_module: str, target_function: str, target_arity: int
+    ) -> int:
+        """
+        Find the number of times a function is called across the codebase.
+
+        Uses the same logic as mcp_server._find_call_sites to resolve aliases
+        and match function calls.
+
+        Args:
+            target_module: Module containing the function
+            target_function: Function name
+            target_arity: Function arity
+
+        Returns:
+            Number of call sites found
+        """
+        call_count = 0
+
+        # Get the function definition line to filter out @spec/@doc
+        function_def_line = None
+        if target_module in self.modules:
+            for func in self.modules[target_module]["functions"]:
+                if func["name"] == target_function and func["arity"] == target_arity:
+                    function_def_line = func["line"]
+                    break
+
+        # Search through all modules for calls
+        for caller_module, module_data in self.modules.items():
+            # Get aliases for resolving calls
+            aliases = module_data.get("aliases", {})
+
+            # Check all calls in this module
+            for call in module_data.get("calls", []):
+                if call["function"] != target_function:
+                    continue
+
+                if call["arity"] != target_arity:
+                    continue
+
+                # Resolve the call's module name using aliases
+                call_module = call.get("module")
+
+                if call_module is None:
+                    # Local call - check if it's in the same module
+                    if caller_module == target_module:
+                        # Filter out calls that are BEFORE the function definition
+                        # (@spec, @doc annotations appear 1-5 lines before the def)
+                        # Only filter if call is before def and within 5 lines
+                        if function_def_line and call["line"] < function_def_line:
+                            if (function_def_line - call["line"]) <= 5:
+                                continue
+                        call_count += 1
+                else:
+                    # Qualified call - resolve the module name
+                    resolved_module = aliases.get(call_module, call_module)
+
+                    # Check if this resolves to our target module
+                    if resolved_module == target_module:
+                        call_count += 1
+
+        return call_count
+
+    def _calculate_confidence(self, module_name: str, module_data: dict) -> str:
+        """
+        Calculate confidence level for a dead code candidate.
+
+        Confidence levels:
+        - high: No usage, no dynamic call indicators, no behaviors/uses
+        - medium: No usage, but module has behaviors or uses (possible callbacks)
+        - low: No usage, but module passed as value (possible dynamic calls)
+
+        Args:
+            module_name: Name of the module
+            module_data: Module metadata
+
+        Returns:
+            Confidence level: "high", "medium", or "low"
+        """
+        # Check if module is used as a value (lowest confidence)
+        if self._is_module_used_as_value(module_name):
+            return "low"
+
+        # Check if module has behaviors or uses (medium confidence)
+        has_behaviour = len(module_data.get("behaviours", [])) > 0
+        has_use = len(module_data.get("uses", [])) > 0
+
+        if has_behaviour or has_use:
+            return "medium"
+
+        # No dynamic indicators - high confidence
+        return "high"
+
+    def _is_module_used_as_value(self, module_name: str) -> bool:
+        """
+        Check if a module is mentioned as a value in any other module.
+
+        When a module is passed as a value, its functions might be called
+        dynamically, so we can't be certain they're unused.
+
+        Args:
+            module_name: Module to check
+
+        Returns:
+            True if module appears in value_mentions of any other module
+        """
+        for other_module, module_data in self.modules.items():
+            if module_name in module_data.get("value_mentions", []):
+                return True
+        return False
+
+    def _find_value_mentioners(self, module_name: str) -> List[dict]:
+        """
+        Find all modules that mention this module as a value.
+
+        Args:
+            module_name: Module to search for
+
+        Returns:
+            List of dicts with {"module": str, "file": str}
+        """
+        mentioners = []
+        for other_module, module_data in self.modules.items():
+            if module_name in module_data.get("value_mentions", []):
+                mentioners.append({"module": other_module, "file": module_data["file"]})
+        return mentioners

cicada/extractors/__init__.py

@@ -0,0 +1,36 @@
+"""
+Extractors for parsing Elixir source code.
+
+This package contains specialized extractors for different parts of Elixir modules.
+
+Author: Cursor(Auto)
+"""
+
+from .module import extract_modules
+from .function import extract_functions
+from .spec import extract_specs, match_specs_to_functions
+from .doc import extract_docs, match_docs_to_functions
+from .dependency import (
+    extract_aliases,
+    extract_imports,
+    extract_requires,
+    extract_uses,
+    extract_behaviours,
+)
+from .call import extract_function_calls, extract_value_mentions
+
+__all__ = [
+    "extract_modules",
+    "extract_functions",
+    "extract_specs",
+    "match_specs_to_functions",
+    "extract_docs",
+    "match_docs_to_functions",
+    "extract_aliases",
+    "extract_imports",
+    "extract_requires",
+    "extract_uses",
+    "extract_behaviours",
+    "extract_function_calls",
+    "extract_value_mentions",
+]

cicada/extractors/base.py

@@ -0,0 +1,66 @@
+"""
+Shared utilities for extractors.
+"""
+
+
+def extract_string_from_arguments(arguments_node, source_code: bytes) -> str | None:
+    """Extract string value from function arguments."""
+    for child in arguments_node.children:
+        # Handle string literals
+        if child.type == "string":
+            # Get the string content (without quotes)
+            string_content = []
+            for string_child in child.children:
+                if string_child.type == "quoted_content":
+                    content = source_code[
+                        string_child.start_byte : string_child.end_byte
+                    ].decode("utf-8")
+                    string_content.append(content)
+
+            if string_content:
+                return "".join(string_content)
+
+        # Handle false (for @moduledoc false)
+        elif child.type == "boolean" or child.type == "atom":
+            value = source_code[child.start_byte : child.end_byte].decode("utf-8")
+            if value == "false":
+                return None
+
+    return None
+
+
+def get_param_name(node, source_code: bytes) -> str | None:
+    """Get parameter name from a parameter node."""
+    # Handle simple identifier: my_arg
+    if node.type == "identifier":
+        return source_code[node.start_byte : node.end_byte].decode("utf-8")
+
+    # Handle pattern match with default: my_arg \\ default_value
+    elif node.type == "binary_operator":
+        for child in node.children:
+            if child.type == "identifier":
+                return source_code[child.start_byte : child.end_byte].decode("utf-8")
+
+    # Handle destructuring: {key, value} or [head | tail]
+    elif node.type in ["tuple", "list", "map"]:
+        # For complex patterns, return the whole pattern as string
+        return source_code[node.start_byte : node.end_byte].decode("utf-8")
+
+    # Handle call patterns (e.g., %Struct{} = arg)
+    elif node.type == "call":
+        # Try to find the actual variable name
+        for child in node.children:
+            if child.type == "identifier":
+                return source_code[child.start_byte : child.end_byte].decode("utf-8")
+
+    # Fallback: return the whole node as string
+    return source_code[node.start_byte : node.end_byte].decode("utf-8")
+
+
+def count_arguments(arguments_node) -> int:
+    """Count the number of arguments in a function call."""
+    count = 0
+    for child in arguments_node.children:
+        if child.type not in [",", "(", ")"]:
+            count += 1
+    return count

cicada/extractors/call.py

@@ -0,0 +1,176 @@
+"""
+Function call and value mention extraction logic.
+"""
+
+from .base import count_arguments
+
+
+def extract_function_calls(node, source_code: bytes) -> list:
+    """Extract all function calls from a module body."""
+    calls = []
+    _find_function_calls_recursive(node, source_code, calls)
+    return calls
+
+
+def _find_function_calls_recursive(node, source_code: bytes, calls: list):
+    """Recursively find function calls."""
+    if node.type == "call":
+        # Check if this is a function definition (def/defp)
+        is_function_def = False
+        for child in node.children:
+            if child.type == "identifier":
+                func_text = source_code[child.start_byte : child.end_byte].decode(
+                    "utf-8"
+                )
+                if func_text in ["def", "defp", "defmodule"]:
+                    is_function_def = True
+                    break
+
+        if is_function_def:
+            # Skip the arguments (which contain the function signature)
+            # but still process the do_block to find calls within the function body
+            for child in node.children:
+                if child.type == "do_block":
+                    _find_function_calls_recursive(child, source_code, calls)
+            return  # Don't process other children
+
+        # Try to extract the function call information
+        call_info = _parse_function_call(node, source_code)
+        if call_info:
+            calls.append(call_info)
+
+    # Recursively search all children
+    for child in node.children:
+        _find_function_calls_recursive(child, source_code, calls)
+
+
+def _parse_function_call(call_node, source_code: bytes) -> dict | None:
+    """
+    Parse a function call to extract the module, function name, arity, and location.
+
+    Handles:
+    - Local calls: func(arg1, arg2)
+    - Module calls: MyModule.func(arg1, arg2)
+    - Aliased calls: User.create(name, email)
+    """
+    line = call_node.start_point[0] + 1
+
+    # Check for dot notation (Module.function)
+    has_dot = False
+    module_name = None
+    function_name = None
+    arguments_node = None
+
+    for child in call_node.children:
+        if child.type == "dot":
+            has_dot = True
+            # Extract module and function from dot
+            for dot_child in child.children:
+                if dot_child.type == "alias":
+                    module_name = source_code[
+                        dot_child.start_byte : dot_child.end_byte
+                    ].decode("utf-8")
+                elif dot_child.type == "identifier":
+                    function_name = source_code[
+                        dot_child.start_byte : dot_child.end_byte
+                    ].decode("utf-8")
+        elif child.type == "identifier" and not has_dot:
+            # Local function call
+            function_name = source_code[child.start_byte : child.end_byte].decode(
+                "utf-8"
+            )
+        elif child.type == "arguments":
+            arguments_node = child
+
+    # Skip certain special forms and macros
+    if function_name in [
+        "alias",
+        "import",
+        "require",
+        "use",
+        "def",
+        "defp",
+        "defmodule",
+        "if",
+        "unless",
+        "case",
+        "cond",
+        "with",
+        "for",
+        "try",
+        "receive",
+    ]:
+        return None
+
+    # Calculate arity
+    arity = 0
+    if arguments_node:
+        arity = count_arguments(arguments_node)
+
+    if function_name:
+        return {
+            "module": module_name,  # None for local calls
+            "function": function_name,
+            "arity": arity,
+            "line": line,
+        }
+
+    return None
+
+
+def extract_value_mentions(node, source_code: bytes) -> list:
+    """Extract all module mentions as values (e.g., module passed as argument)."""
+    value_mentions = []
+    _find_value_mentions_recursive(node, source_code, value_mentions)
+    # Return unique module names
+    return list(set(value_mentions))
+
+
+def _find_value_mentions_recursive(node, source_code: bytes, value_mentions: list):
+    """Recursively find module value mentions."""
+    # Look for alias nodes that are NOT part of alias/import/require/use declarations
+    # and are NOT part of module function calls (which are already tracked in calls)
+
+    if node.type == "alias":
+        # Check if this is a standalone alias (value mention)
+        # Skip if parent is a specific call type
+
+        # Get the module name
+        module_name = source_code[node.start_byte : node.end_byte].decode("utf-8")
+
+        # We need to check if this alias is part of a call with dot notation
+        # If it has a dot parent, it's a module function call, not a value mention
+        is_in_call = False
+        current = node
+
+        # Check ancestors to see if we're in a special context
+        for _ in range(3):  # Check up to 3 levels up
+            if current.parent:
+                current = current.parent
+                if current.type == "call":
+                    # Check if this is alias/import/require/use/defmodule
+                    for child in current.children:
+                        if child.type == "identifier":
+                            func_text = source_code[
+                                child.start_byte : child.end_byte
+                            ].decode("utf-8")
+                            if func_text in [
+                                "alias",
+                                "import",
+                                "require",
+                                "use",
+                                "defmodule",
+                            ]:
+                                is_in_call = True
+                                break
+                elif current.type == "dot":
+                    # This alias is part of a Module.function call
+                    is_in_call = True
+                    break
+
+        if not is_in_call:
+            value_mentions.append(module_name)
+
+    # Recursively search all children
+    for child in node.children:
+        _find_value_mentions_recursive(child, source_code, value_mentions)