cicada-mcp 0.1.4__py3-none-any.whl

cicada/extractors/function.py

@@ -0,0 +1,246 @@
+"""
+Function extraction logic.
+
+Author: Cursor(Auto)
+"""
+
+from .base import get_param_name
+
+
+def extract_functions(node, source_code: bytes) -> list:
+    """Extract all function definitions from a module body."""
+    functions = []
+    _find_functions_recursive(node, source_code, functions)
+    return functions
+
+
+def _extract_impl_from_prev_sibling(node, source_code: bytes):
+    """
+    Extract @impl value from previous sibling if it's an @impl attribute.
+
+    Returns:
+        - True if @impl true
+        - Module name (str) if @impl ModuleName
+        - None if not an @impl attribute
+    """
+    if node is None or node.type != "unary_operator":
+        return None
+
+    # Check if this is an @ operator
+    is_at_operator = False
+    impl_call = None
+
+    for child in node.children:
+        if child.type == "@":
+            is_at_operator = True
+        elif child.type == "call" and is_at_operator:
+            impl_call = child
+            break
+
+    if not impl_call:
+        return None
+
+    # Check if the call is "impl"
+    identifier_text = None
+    arguments_node = None
+
+    for child in impl_call.children:
+        if child.type == "identifier":
+            identifier_text = source_code[child.start_byte : child.end_byte].decode(
+                "utf-8"
+            )
+        elif child.type == "arguments":
+            arguments_node = child
+
+    if identifier_text != "impl":
+        return None
+
+    # Extract the impl value from arguments
+    if arguments_node:
+        for arg_child in arguments_node.children:
+            if arg_child.type == "boolean":
+                # @impl true or @impl false
+                bool_text = source_code[
+                    arg_child.start_byte : arg_child.end_byte
+                ].decode("utf-8")
+                return bool_text == "true"
+            elif arg_child.type == "alias":
+                # @impl ModuleName
+                module_name = source_code[
+                    arg_child.start_byte : arg_child.end_byte
+                ].decode("utf-8")
+                return module_name
+
+    # @impl without arguments defaults to true
+    return True
+
+
+def _find_functions_recursive(node, source_code: bytes, functions: list):
+    """Recursively find def and defp declarations."""
+    # Track previous sibling to detect @impl attributes
+    prev_sibling = None
+
+    # Iterate through children to process siblings
+    for child in node.children:
+        # Check if this child is a function call (def or defp)
+        if child.type == "call":
+            # Get the target (function name)
+            target = None
+            arguments = None
+
+            for call_child in child.children:
+                if call_child.type == "identifier":
+                    target = call_child
+                elif call_child.type == "arguments":
+                    arguments = call_child
+
+            # Check if this is a def or defp call
+            if target and arguments:
+                target_text = source_code[target.start_byte : target.end_byte].decode(
+                    "utf-8"
+                )
+
+                if target_text in ["def", "defp"]:
+                    # Check if previous sibling is @impl
+                    impl_value = _extract_impl_from_prev_sibling(
+                        prev_sibling, source_code
+                    )
+
+                    # Extract function name and arity
+                    func_info = _parse_function_definition(
+                        arguments, source_code, target_text, child.start_point[0] + 1
+                    )
+                    if func_info:
+                        # Add impl attribute if present
+                        if impl_value is not None:
+                            func_info["impl"] = impl_value
+                        else:
+                            func_info["impl"] = False
+                        functions.append(func_info)
+                        prev_sibling = child
+                        continue  # Don't recurse into function body
+
+        # Recursively process this child
+        _find_functions_recursive(child, source_code, functions)
+        prev_sibling = child
+
+
+def _parse_function_definition(
+    arguments_node, source_code: bytes, func_type: str, line: int
+) -> dict | None:
+    """Parse a function definition to extract name, arity, argument names, and guards."""
+    func_name = None
+    arity = 0
+    arg_names = []
+    guards = []
+
+    for arg_child in arguments_node.children:
+        # The function signature can be either:
+        # 1. A call node (function with params): func_name(param1, param2)
+        # 2. An identifier (function with no params): func_name
+        # 3. A binary_operator (when guards are present): func_name(params) when guard
+        if arg_child.type == "call":
+            # Extract function name from call target
+            for call_child in arg_child.children:
+                if call_child.type == "identifier":
+                    func_name = source_code[
+                        call_child.start_byte : call_child.end_byte
+                    ].decode("utf-8")
+                elif call_child.type == "arguments":
+                    arg_names = _extract_argument_names(call_child, source_code)
+                    arity = len(arg_names)
+            break
+        elif arg_child.type == "binary_operator":
+            # This handles guards: func_name(params) when guard_expr
+            # The binary_operator contains the call as its first child
+            for op_child in arg_child.children:
+                if op_child.type == "call":
+                    # Extract function name and args from the call
+                    for call_child in op_child.children:
+                        if call_child.type == "identifier":
+                            func_name = source_code[
+                                call_child.start_byte : call_child.end_byte
+                            ].decode("utf-8")
+                        elif call_child.type == "arguments":
+                            arg_names = _extract_argument_names(call_child, source_code)
+                            arity = len(arg_names)
+                    break
+            break
+        elif arg_child.type == "identifier":
+            func_name = source_code[arg_child.start_byte : arg_child.end_byte].decode(
+                "utf-8"
+            )
+            arity = 0
+            arg_names = []
+            break
+
+    # Extract guard clauses
+    guards = _extract_guards(arguments_node, source_code)
+
+    if func_name:
+        return {
+            "name": func_name,
+            "arity": arity,
+            "args": arg_names,
+            "guards": guards,
+            "full_name": f"{func_name}/{arity}",
+            "line": line,
+            "signature": f"{func_type} {func_name}",
+            "type": func_type,
+        }
+
+    return None
+
+
+def _extract_guards(arguments_node, source_code: bytes) -> list[str]:
+    """
+    Extract guard clauses from function definition arguments.
+
+    Example:
+        def abs_value(n) when n < 0, do: -n
+        Returns: ["n < 0"]
+
+    Tree structure:
+        arguments:
+          binary_operator:  # This contains function_call WHEN guard_expr
+            call: abs_value(n)
+            when: 'when'
+            binary_operator: n < 0  # This is the guard expression
+    """
+    guards = []
+
+    for arg_child in arguments_node.children:
+        # Guards appear as binary_operator nodes containing 'when'
+        if arg_child.type == "binary_operator":
+            # Look for 'when' keyword and the guard expression after it
+            has_when = False
+
+            for op_child in arg_child.children:
+                if op_child.type == "when":
+                    has_when = True
+                elif has_when:
+                    # This is the guard expression node (comes after 'when')
+                    # It's typically a binary_operator (like n < 0)
+                    guard_expr = source_code[
+                        op_child.start_byte : op_child.end_byte
+                    ].decode("utf-8")
+                    guards.append(guard_expr)
+                    break
+
+    return guards
+
+
+def _extract_argument_names(params_node, source_code: bytes) -> list[str]:
+    """Extract parameter names from function arguments."""
+    arg_names = []
+
+    for child in params_node.children:
+        if child.type in [",", "(", ")", "[", "]"]:
+            continue
+
+        # Extract the argument name (simplified - handles basic cases)
+        arg_name = get_param_name(child, source_code)
+        if arg_name:
+            arg_names.append(arg_name)
+
+    return arg_names

cicada/extractors/module.py

@@ -0,0 +1,123 @@
+"""
+Module extraction logic.
+"""
+
+from .base import extract_string_from_arguments
+
+
+def extract_modules(root_node, source_code: bytes) -> list:
+    """Extract all modules from the syntax tree."""
+    modules = []
+    _find_modules_recursive(root_node, source_code, modules)
+    return modules
+
+
+def _find_modules_recursive(node, source_code: bytes, modules: list):
+    """Recursively find defmodule declarations."""
+    # Check if this node is a function call (defmodule)
+    if node.type == "call":
+        # Get the target, arguments, and do_block (all siblings)
+        target = None
+        arguments = None
+        do_block = None
+
+        for child in node.children:
+            if child.type == "identifier":
+                target = child
+            elif child.type == "arguments":
+                arguments = child
+            elif child.type == "do_block":
+                do_block = child
+
+        # Check if this is a defmodule call
+        if target and arguments:
+            target_text = source_code[target.start_byte : target.end_byte].decode(
+                "utf-8"
+            )
+
+            if target_text == "defmodule":
+                # Extract module name from arguments
+                module_name = None
+
+                for arg_child in arguments.children:
+                    if arg_child.type == "alias":
+                        module_name = source_code[
+                            arg_child.start_byte : arg_child.end_byte
+                        ].decode("utf-8")
+                        break
+
+                if module_name and do_block:
+                    module_info = {
+                        "module": module_name,
+                        "line": node.start_point[0] + 1,
+                        "moduledoc": extract_moduledoc(do_block, source_code),
+                        "do_block": do_block,  # Store for further extraction
+                    }
+                    modules.append(module_info)
+                    return  # Don't recurse into module body
+
+    # Recursively process children
+    for child in node.children:
+        _find_modules_recursive(child, source_code, modules)
+
+
+def extract_moduledoc(node, source_code: bytes) -> str | None:
+    """Extract the @moduledoc attribute from a module's do_block."""
+    return _find_moduledoc_recursive(node, source_code)
+
+
+def _find_moduledoc_recursive(node, source_code: bytes) -> str | None:
+    """Recursively search for @moduledoc attribute."""
+    # 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":
+                # @moduledoc "..." is represented as a call
+                operand = child
+
+        if operator and operand:
+            # Check if this is a moduledoc attribute
+            for call_child in operand.children:
+                if call_child.type == "identifier":
+                    attr_name = source_code[
+                        call_child.start_byte : call_child.end_byte
+                    ].decode("utf-8")
+
+                    if attr_name == "moduledoc":
+                        # Extract the documentation string from the arguments
+                        for arg_child in operand.children:
+                            if arg_child.type == "arguments":
+                                doc_string = extract_string_from_arguments(
+                                    arg_child, source_code
+                                )
+                                if doc_string:
+                                    return doc_string
+
+    # Recursively search children (only in the immediate do_block, not nested modules)
+    for child in node.children:
+        # Don't recurse into nested defmodule
+        if child.type == "call":
+            # Check if it's a defmodule
+            is_defmodule = False
+            for call_child in child.children:
+                if call_child.type == "identifier":
+                    target_text = source_code[
+                        call_child.start_byte : call_child.end_byte
+                    ].decode("utf-8")
+                    if target_text == "defmodule":
+                        is_defmodule = True
+                        break
+
+            if is_defmodule:
+                continue
+
+        result = _find_moduledoc_recursive(child, source_code)
+        if result:
+            return result
+
+    return None

cicada/extractors/spec.py

@@ -0,0 +1,151 @@
+"""
+Type spec extraction logic.
+"""
+
+
+def extract_specs(node, source_code: bytes) -> dict:
+    """Extract all @spec attributes from a module body."""
+    specs = {}
+    _find_specs_recursive(node, source_code, specs)
+    return specs
+
+
+def _find_specs_recursive(node, source_code: bytes, specs: dict):
+    """Recursively find @spec 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 spec attribute
+            for call_child in operand.children:
+                if call_child.type == "identifier":
+                    attr_name = source_code[
+                        call_child.start_byte : call_child.end_byte
+                    ].decode("utf-8")
+
+                    if attr_name == "spec":
+                        # Extract the spec definition
+                        spec_info = _parse_spec(operand, source_code)
+                        if spec_info:
+                            key = f"{spec_info['name']}/{spec_info['arity']}"
+                            specs[key] = spec_info
+
+    # Recursively search children
+    for child in node.children:
+        # Don't recurse into nested defmodule or function definitions
+        if child.type == "call":
+            is_defmodule_or_def = False
+            for call_child in child.children:
+                if call_child.type == "identifier":
+                    target_text = source_code[
+                        call_child.start_byte : call_child.end_byte
+                    ].decode("utf-8")
+                    if target_text in ["defmodule", "def", "defp"]:
+                        is_defmodule_or_def = True
+                        break
+
+            if is_defmodule_or_def:
+                continue
+
+        _find_specs_recursive(child, source_code, specs)
+
+
+def _parse_spec(spec_node, source_code: bytes) -> dict | None:
+    """Parse a @spec attribute to extract function name, arity, parameter types, and return type."""
+    # @spec is represented as: spec(function_signature)
+    # We need to find the arguments node and parse the typespec
+
+    for child in spec_node.children:
+        if child.type == "arguments":
+            # The typespec is in the arguments
+            for arg in child.children:
+                if arg.type == "binary_operator":
+                    # This is the :: operator separating params from return type
+                    # Left side has the function call with params
+                    # Right side has the return type
+                    func_call = None
+                    return_type = None
+                    found_call = False
+
+                    for op_child in arg.children:
+                        if op_child.type == "call":
+                            func_call = op_child
+                            found_call = True
+                        elif found_call and op_child.type not in ["::", "operator"]:
+                            # This is the return type node (after :: operator)
+                            return_type = source_code[
+                                op_child.start_byte : op_child.end_byte
+                            ].decode("utf-8")
+
+                    if func_call:
+                        func_name = None
+                        param_types = []
+
+                        for fc_child in func_call.children:
+                            if fc_child.type == "identifier":
+                                func_name = source_code[
+                                    fc_child.start_byte : fc_child.end_byte
+                                ].decode("utf-8")
+                            elif fc_child.type == "arguments":
+                                param_types = _extract_param_types(
+                                    fc_child, source_code
+                                )
+
+                        if func_name:
+                            return {
+                                "name": func_name,
+                                "arity": len(param_types),
+                                "param_types": param_types,
+                                "return_type": return_type,
+                            }
+
+    return None
+
+
+def _extract_param_types(params_node, source_code: bytes) -> list[str]:
+    """Extract parameter type strings from @spec arguments."""
+    param_types = []
+
+    for child in params_node.children:
+        if child.type in [",", "(", ")", "[", "]"]:
+            continue
+
+        # Get the type as a string
+        type_str = source_code[child.start_byte : child.end_byte].decode("utf-8")
+        param_types.append(type_str)
+
+    return param_types
+
+
+def match_specs_to_functions(functions: list, specs: dict) -> list:
+    """Match specs with functions and add type information to function args and return type."""
+    for func in functions:
+        key = f"{func['name']}/{func['arity']}"
+        if key in specs:
+            spec = specs[key]
+            # Add types to arguments
+            if "args" in func and "param_types" in spec:
+                # Create args_with_types list
+                args_with_types = []
+                for i, arg_name in enumerate(func["args"]):
+                    if i < len(spec["param_types"]):
+                        args_with_types.append(
+                            {"name": arg_name, "type": spec["param_types"][i]}
+                        )
+                    else:
+                        args_with_types.append({"name": arg_name, "type": None})
+                func["args_with_types"] = args_with_types
+
+            # Add return type from spec
+            if "return_type" in spec and spec["return_type"]:
+                func["return_type"] = spec["return_type"]
+
+    return functions