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

cicada/dead_code/__init__.py

@@ -0,0 +1 @@
+"""Dead code analysis module - finds and analyzes unused code in Elixir projects."""

cicada/{find_dead_code.py → dead_code/finder.py}

@@ -11,9 +11,10 @@ import argparse
 import json
 import sys
 
-from cicada.dead_code_analyzer import DeadCodeAnalyzer
 from cicada.utils import get_index_path, load_index
 
+from .analyzer import DeadCodeAnalyzer
+
 
 def format_markdown(results: dict) -> str:
     """

cicada/dependency_analyzer.py

@@ -0,0 +1,147 @@
+"""
+Dependency analysis for Elixir modules and functions.
+
+This module processes already-extracted AST data (aliases, imports, uses, calls)
+to produce clean dependency information.
+"""
+
+
+def _resolve_module_alias(module_name: str, aliases: dict) -> str:
+    """
+    Resolve a module name using the alias mapping.
+
+    Args:
+        module_name: Short or full module name
+        aliases: Dict mapping short names to full names
+
+    Returns:
+        Full module name (resolved if aliased, otherwise unchanged)
+    """
+    return aliases.get(module_name, module_name)
+
+
+def extract_module_dependencies(module_data: dict) -> dict:
+    """
+    Extract module-level dependencies from parsed module data.
+
+    Args:
+        module_data: Dictionary containing module information with:
+            - aliases: Dict mapping short names to full module names
+            - imports: List of imported module names
+            - uses: List of used module names
+            - requires: List of required module names (optional)
+            - behaviours: List of behaviour module names (optional)
+            - calls: List of function calls with module, function, arity, line
+
+    Returns:
+        Dictionary with:
+            - modules: Set of module names this module depends on
+            - has_dynamic_calls: Boolean indicating if there are unresolved calls
+    """
+    dependencies = set()
+    aliases = module_data.get("aliases", {})
+
+    # Add dependencies from various sources
+    # Note: we use aliases.values() to get full names, not short names
+    for _source_key, extract_values in [
+        ("aliases", lambda: aliases.values()),
+        ("imports", lambda: module_data.get("imports", [])),
+        ("uses", lambda: module_data.get("uses", [])),
+        ("requires", lambda: module_data.get("requires", [])),
+        ("behaviours", lambda: module_data.get("behaviours", [])),
+    ]:
+        dependencies.update(extract_values())
+
+    # Add dependencies from function calls (with alias resolution)
+    for call in module_data.get("calls", []):
+        module_name = call.get("module")
+        if module_name:
+            resolved_module = _resolve_module_alias(module_name, aliases)
+            # Exclude Kernel module (too noisy)
+            if resolved_module != "Kernel":
+                dependencies.add(resolved_module)
+
+    return {
+        "modules": sorted(dependencies),
+        "has_dynamic_calls": False,  # Could be enhanced to detect apply() etc.
+    }
+
+
+def extract_function_dependencies(
+    module_data: dict,
+    function_data: dict,
+    all_module_calls: list,
+    function_end_line: int,
+) -> list:
+    """
+    Extract function-level dependencies from function calls.
+
+    Args:
+        module_data: Dictionary containing module information (for alias resolution)
+        function_data: Dictionary containing function information (name, arity, line)
+        all_module_calls: List of ALL calls in the module
+        function_end_line: The line where the function ends
+
+    Returns:
+        List of dictionaries, each containing:
+            - module: Module name (resolved from aliases)
+            - function: Function name
+            - arity: Function arity
+            - line: Line number where called
+    """
+    module_name = module_data.get("module")
+    aliases = module_data.get("aliases", {})
+    function_start_line = function_data.get("line")
+
+    # Filter calls to only those within this function's line range
+    function_calls = [
+        call
+        for call in all_module_calls
+        if function_start_line is not None
+        and call.get("line") is not None
+        and function_start_line <= call["line"] <= function_end_line
+    ]
+
+    dependencies = []
+    for call in function_calls:
+        # Resolve module name (external calls use aliases, local calls use current module)
+        call_module = call.get("module")
+        resolved_module = (
+            _resolve_module_alias(call_module, aliases) if call_module else module_name
+        )
+
+        dependencies.append(
+            {
+                "module": resolved_module,
+                "function": call.get("function"),
+                "arity": call.get("arity"),
+                "line": call.get("line"),
+            }
+        )
+
+    return dependencies
+
+
+def calculate_function_end_line(function_data: dict, next_function_line: int | None) -> int:
+    """
+    Calculate the end line of a function.
+
+    Args:
+        function_data: Dictionary containing function information
+        next_function_line: Line number of the next function, or None if this is the last function
+
+    Returns:
+        Estimated end line of the function
+    """
+    function_line = function_data.get("line")
+
+    if next_function_line:
+        # Function ends just before the next function
+        return next_function_line - 1
+    elif function_line is not None:
+        # Last function - use a large number as end line
+        # This is a heuristic; ideally we'd get the actual end line from the AST
+        return function_line + 10000
+    else:
+        # If no line info, return a large number
+        return 99999999

cicada/entry_utils.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable, Sequence
+
+from cicada import commands as _commands_module
+
+KNOWN_SUBCOMMANDS_SET = getattr(_commands_module, "KNOWN_SUBCOMMANDS_SET", frozenset())
+get_argument_parser = _commands_module.get_argument_parser
+handle_command = _commands_module.handle_command
+
+DefaultResolver = Callable[[], str | None] | str | None
+
+
+def prepare_argv(
+    argv: Sequence[str],
+    *,
+    default_on_unknown: str | None,
+    default_on_none: DefaultResolver,
+    default_on_unknown_args: Sequence[str] | None = None,
+    default_on_none_args: Sequence[str] | None = None,
+) -> list[str]:
+    """
+    Normalize argv so both entry points share identical subcommand routing.
+
+    - If the first argument is an unknown token (and not a flag), inject the default subcommand and any associated args.
+    - If no arguments are provided, append the default-on-none subcommand (with optional extra args).
+    """
+    normalized = list(argv)
+
+    if len(normalized) > 1:
+        first_arg = normalized[1]
+        if (
+            default_on_unknown
+            and first_arg not in KNOWN_SUBCOMMANDS_SET
+            and not first_arg.startswith("-")
+        ):
+            extras = list(default_on_unknown_args or ())
+            normalized[1:1] = [default_on_unknown, *extras]
+    elif len(normalized) == 1:
+        default_command = _resolve_default(default_on_none)
+        if default_command:
+            extras = list(default_on_none_args or ())
+            normalized.append(default_command)
+            if extras:
+                normalized.extend(extras)
+
+    return normalized
+
+
+def run_cli(
+    *,
+    prog_name: str,
+    version_prog_name: str,
+    default_on_unknown: str | None,
+    default_on_none: DefaultResolver,
+    default_on_unknown_args: Sequence[str] | None = None,
+    default_on_none_args: Sequence[str] | None = None,
+) -> None:
+    """Shared entry-point runner for cicada and cicada-mcp."""
+    argv = list(sys.argv)
+    _maybe_print_version(argv, version_prog_name)
+
+    normalized = prepare_argv(
+        argv,
+        default_on_unknown=default_on_unknown,
+        default_on_none=default_on_none,
+        default_on_unknown_args=default_on_unknown_args,
+        default_on_none_args=default_on_none_args,
+    )
+
+    parser = get_argument_parser()
+    parser.prog = prog_name
+    args = parser.parse_args(normalized[1:])
+
+    if not handle_command(args):
+        parser.print_help()
+        sys.exit(1)
+
+
+def _resolve_default(spec: DefaultResolver) -> str | None:
+    if callable(spec):
+        return spec()
+    return spec
+
+
+def _maybe_print_version(argv: Sequence[str], prog_name: str) -> None:
+    if len(argv) > 1 and argv[1] in ("--version", "-v"):
+        from cicada.version_check import get_version_string
+
+        print(f"{prog_name} {get_version_string()}")
+        sys.exit(0)

cicada/extractors/base.py

@@ -2,6 +2,8 @@
 Shared utilities for extractors.
 """
 
+from cicada.utils import extract_text_from_node
+
 
 def extract_string_from_arguments(arguments_node, source_code: bytes) -> str | None:
     """Extract string value from function arguments."""
@@ -12,9 +14,7 @@ def extract_string_from_arguments(arguments_node, source_code: bytes) -> str | N
             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"
-                    )
+                    content = extract_text_from_node(string_child, source_code)
                     string_content.append(content)
 
             if string_content:
@@ -22,7 +22,7 @@ def extract_string_from_arguments(arguments_node, source_code: bytes) -> str | N
 
         # 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")
+            value = extract_text_from_node(child, source_code)
             if value == "false":
                 return None
 
@@ -33,28 +33,28 @@ 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")
+        return extract_text_from_node(node, source_code)
 
     # 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")
+                return extract_text_from_node(child, source_code)
 
     # 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")
+        return extract_text_from_node(node, source_code)
 
     # 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")
+                return extract_text_from_node(child, source_code)
 
     # Fallback: return the whole node as string
-    return source_code[node.start_byte : node.end_byte].decode("utf-8")
+    return extract_text_from_node(node, source_code)
 
 
 def count_arguments(arguments_node) -> int:

cicada/extractors/call.py

@@ -2,6 +2,8 @@
 Function call and value mention extraction logic.
 """
 
+from cicada.utils import extract_text_from_node, is_function_definition_call
+
 from .base import count_arguments
 
 
@@ -14,17 +16,18 @@ def extract_function_calls(node, source_code: bytes) -> list:
 
 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
+    # Skip module attributes (@spec, @doc, @moduledoc, @type, etc.)
+    # These are wrapped in unary_operator nodes with @ token
+    if node.type == "unary_operator":
+        # Check if this is a module attribute (starts with @)
         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 child.type == "@":
+                # This is a module attribute, skip the entire subtree
+                return
 
-        if is_function_def:
+    if node.type == "call":
+        # Check if this is a function definition (def/defp)
+        if is_function_definition_call(node, source_code):
             # 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:
@@ -65,16 +68,12 @@ def _parse_function_call(call_node, source_code: bytes) -> dict | None:
             # 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"
-                    )
+                    module_name = extract_text_from_node(dot_child, source_code)
                 elif dot_child.type == "identifier":
-                    function_name = source_code[dot_child.start_byte : dot_child.end_byte].decode(
-                        "utf-8"
-                    )
+                    function_name = extract_text_from_node(dot_child, source_code)
         elif child.type == "identifier" and not has_dot:
             # Local function call
-            function_name = source_code[child.start_byte : child.end_byte].decode("utf-8")
+            function_name = extract_text_from_node(child, source_code)
         elif child.type == "arguments":
             arguments_node = child
 
@@ -132,7 +131,7 @@ def _find_value_mentions_recursive(node, source_code: bytes, value_mentions: lis
         # 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")
+        module_name = extract_text_from_node(node, source_code)
 
         # 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
@@ -147,9 +146,7 @@ def _find_value_mentions_recursive(node, source_code: bytes, value_mentions: lis
                     # 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"
-                            )
+                            func_text = extract_text_from_node(child, source_code)
                             if func_text in [
                                 "alias",
                                 "import",

cicada/extractors/common.py

@@ -0,0 +1,64 @@
+from cicada.utils import extract_text_from_node, is_function_definition_call
+
+
+def _find_nodes_recursive(node, source_code: bytes, results: list, node_type: str, parse_function):
+    """Recursively find nodes of a specific type and parse them."""
+    if node.type == node_type:
+        result = parse_function(node, source_code)
+        if result:
+            if isinstance(result, list):
+                results.extend(result)
+            else:
+                results.append(result)
+
+    # Recursively search children, but skip function bodies
+    for child in node.children:
+        if child.type == "call" and is_function_definition_call(child, source_code):
+            continue
+
+        _find_nodes_recursive(child, source_code, results, node_type, parse_function)
+
+
+def _find_attribute_recursive(
+    node, source_code: bytes, attributes: dict, attribute_name: str, parse_function
+):
+    """Recursively find attribute declarations."""
+    # Look for unary_operator nodes (which represent @ attributes)
+    if node.type == "unary_operator":
+        operator = None
+        operand = None
+
+        for child in node.children:
+            if child.type == "@":
+                operator = child
+            elif child.type == "call":
+                operand = child
+
+        if operator and operand:
+            # Check if this is a doc attribute
+            for call_child in operand.children:
+                if call_child.type == "identifier":
+                    attr_name = extract_text_from_node(call_child, source_code)
+
+                    if attr_name == attribute_name:
+                        # Extract the doc definition
+                        if attribute_name == "spec":
+                            attribute_info = parse_function(operand, source_code)
+                        else:
+                            attribute_info = parse_function(
+                                operand, source_code, node.start_point[0] + 1
+                            )
+                        if attribute_info:
+                            if attribute_name == "doc":
+                                attributes[attribute_info["line"]] = attribute_info
+                            elif attribute_name == "spec":
+                                key = f"{attribute_info['name']}/{attribute_info['arity']}"
+                                attributes[key] = attribute_info
+
+    # Recursively search children
+    for child in node.children:
+        # Don't recurse into nested defmodule or function definitions
+        if child.type == "call" and is_function_definition_call(child, source_code):
+            continue
+
+        _find_attribute_recursive(child, source_code, attributes, attribute_name, parse_function)