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

cicada/extractors/dependency.py

@@ -4,53 +4,49 @@ Dependency extraction logic (alias, import, require, use).
 Author: Cursor(Auto)
 """
 
+from cicada.utils import extract_text_from_node
+
+from .common import _find_nodes_recursive
+
 
 def extract_aliases(node, source_code: bytes) -> dict:
     """Extract all alias declarations from a module body."""
-    aliases = {}
+    aliases = []
     _find_aliases_recursive(node, source_code, aliases)
-    return aliases
 
+    result = {}
+    for alias in aliases:
+        if alias:
+            result.update(alias)
+    return result
 
-def _find_aliases_recursive(node, source_code: bytes, aliases: dict):
-    """Recursively find alias declarations."""
-    if node.type == "call":
-        target = None
-        arguments = None
 
-        for child in node.children:
-            if child.type == "identifier":
-                target = child
-            elif child.type == "arguments":
-                arguments = child
+def _parse_alias_call(node, source_code: bytes) -> dict | None:
+    """Parse an alias call and return the alias information."""
+    target = None
+    arguments = None
 
-        if target and arguments:
-            target_text = source_code[target.start_byte : target.end_byte].decode("utf-8")
+    for child in node.children:
+        if child.type == "identifier":
+            target = child
+        elif child.type == "arguments":
+            arguments = child
 
-            if target_text == "alias":
-                # Parse the alias
-                alias_info = _parse_alias(arguments, source_code)
-                if alias_info:
-                    # alias_info is a dict of {short_name: full_name}
-                    aliases.update(alias_info)
+    if target and arguments:
+        target_text = extract_text_from_node(target, source_code)
 
-    # Recursively search children, but skip function bodies
-    for child in node.children:
-        if child.type == "call":
-            is_function_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 ["def", "defp", "defmodule"]:
-                        is_function_def = True
-                        break
+        if target_text == "alias":
+            # Parse the alias
+            alias_info = _parse_alias(arguments, source_code)
+            if alias_info:
+                # alias_info is a dict of {short_name: full_name}
+                return alias_info
+    return None
 
-            if is_function_def:
-                continue
 
-        _find_aliases_recursive(child, source_code, aliases)
+def _find_aliases_recursive(node, source_code: bytes, aliases: list):
+    """Recursively find alias declarations."""
+    _find_nodes_recursive(node, source_code, aliases, "call", _parse_alias_call)
 
 
 def _parse_alias(arguments_node, source_code: bytes) -> dict | None:
@@ -67,7 +63,7 @@ def _parse_alias(arguments_node, source_code: bytes) -> dict | None:
     for arg_child in arguments_node.children:
         # Simple alias: alias MyApp.User
         if arg_child.type == "alias":
-            full_name = source_code[arg_child.start_byte : arg_child.end_byte].decode("utf-8")
+            full_name = extract_text_from_node(arg_child, source_code)
             # Get the last part as the short name
             short_name = full_name.split(".")[-1]
             result[short_name] = full_name
@@ -80,9 +76,7 @@ def _parse_alias(arguments_node, source_code: bytes) -> dict | None:
 
             for dot_child in arg_child.children:
                 if dot_child.type == "alias":
-                    module_prefix = source_code[dot_child.start_byte : dot_child.end_byte].decode(
-                        "utf-8"
-                    )
+                    module_prefix = extract_text_from_node(dot_child, source_code)
                 elif dot_child.type == "tuple":
                     tuple_node = dot_child
 
@@ -90,9 +84,7 @@ def _parse_alias(arguments_node, source_code: bytes) -> dict | None:
                 # Extract each alias from the tuple
                 for tuple_child in tuple_node.children:
                     if tuple_child.type == "alias":
-                        short_name = source_code[
-                            tuple_child.start_byte : tuple_child.end_byte
-                        ].decode("utf-8")
+                        short_name = extract_text_from_node(tuple_child, source_code)
                         full_name = f"{module_prefix}.{short_name}"
                         result[short_name] = full_name
 
@@ -106,22 +98,16 @@ def _parse_alias(arguments_node, source_code: bytes) -> dict | None:
                     for pair_child in kw_child.children:
                         if pair_child.type == "keyword":
                             # Get keyword text (e.g., "as:")
-                            key_text = source_code[
-                                pair_child.start_byte : pair_child.end_byte
-                            ].decode("utf-8")
+                            key_text = extract_text_from_node(pair_child, source_code)
                         elif pair_child.type == "alias":
-                            alias_name = source_code[
-                                pair_child.start_byte : pair_child.end_byte
-                            ].decode("utf-8")
+                            alias_name = extract_text_from_node(pair_child, source_code)
 
                     # If we found 'as:', update the result to use custom name
                     if key_text and "as" in key_text and alias_name:
                         # Get the full module name from previous arg
                         for prev_arg in arguments_node.children:
                             if prev_arg.type == "alias":
-                                full_name = source_code[
-                                    prev_arg.start_byte : prev_arg.end_byte
-                                ].decode("utf-8")
+                                full_name = extract_text_from_node(prev_arg, source_code)
                                 # Remove the default short name and add custom one
                                 result.clear()
                                 result[alias_name] = full_name
@@ -132,153 +118,67 @@ def _parse_alias(arguments_node, source_code: bytes) -> dict | None:
 
 def extract_imports(node, source_code: bytes) -> list:
     """Extract all import declarations from a module body."""
+
     imports = []
-    _find_imports_recursive(node, source_code, imports)
-    return imports
 
+    _find_declarations_recursive(node, source_code, imports, "import")
 
-def _find_imports_recursive(node, source_code: bytes, imports: list):
-    """Recursively find import declarations."""
-    if node.type == "call":
-        target = None
-        arguments = None
+    return imports
 
-        for child in node.children:
-            if child.type == "identifier":
-                target = child
-            elif child.type == "arguments":
-                arguments = child
-
-        if target and arguments:
-            target_text = source_code[target.start_byte : target.end_byte].decode("utf-8")
-
-            if target_text == "import":
-                # Parse the import - imports are simpler than aliases
-                # import MyModule or import MyModule, only: [func: 1]
-                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"
-                        )
-                        imports.append(module_name)
-
-    # Recursively search children, but skip function bodies
-    for child in node.children:
-        if child.type == "call":
-            is_function_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 ["def", "defp", "defmodule"]:
-                        is_function_def = True
-                        break
 
-            if is_function_def:
-                continue
+def _parse_declaration_call(node, source_code: bytes, declaration_name: str) -> str | None:
+    """Parse a declaration call and return the module name."""
+    target = None
+    arguments = None
 
-        _find_imports_recursive(child, source_code, imports)
+    for child in node.children:
+        if child.type == "identifier":
+            target = child
+        elif child.type == "arguments":
+            arguments = child
+
+    if target and arguments:
+        target_text = extract_text_from_node(target, source_code)
+
+        if target_text == declaration_name:
+            # Parse the declaration
+            for arg_child in arguments.children:
+                if arg_child.type == "alias":
+                    return extract_text_from_node(arg_child, source_code)
+    return None
+
+
+def _find_declarations_recursive(
+    node, source_code: bytes, declarations: list, declaration_name: str
+):
+    """Recursively find declarations."""
+    _find_nodes_recursive(
+        node,
+        source_code,
+        declarations,
+        "call",
+        lambda n, s: _parse_declaration_call(n, s, declaration_name),
+    )
 
 
 def extract_requires(node, source_code: bytes) -> list:
     """Extract all require declarations from a module body."""
-    requires = []
-    _find_requires_recursive(node, source_code, requires)
-    return requires
-
-
-def _find_requires_recursive(node, source_code: bytes, requires: list):
-    """Recursively find require declarations."""
-    if node.type == "call":
-        target = None
-        arguments = None
-
-        for child in node.children:
-            if child.type == "identifier":
-                target = child
-            elif child.type == "arguments":
-                arguments = child
-
-        if target and arguments:
-            target_text = source_code[target.start_byte : target.end_byte].decode("utf-8")
 
-            if target_text == "require":
-                # Parse the require
-                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"
-                        )
-                        requires.append(module_name)
-
-    # Recursively search children, but skip function bodies
-    for child in node.children:
-        if child.type == "call":
-            is_function_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 ["def", "defp", "defmodule"]:
-                        is_function_def = True
-                        break
+    requires = []
 
-            if is_function_def:
-                continue
+    _find_declarations_recursive(node, source_code, requires, "require")
 
-        _find_requires_recursive(child, source_code, requires)
+    return requires
 
 
 def extract_uses(node, source_code: bytes) -> list:
     """Extract all use declarations from a module body."""
-    uses = []
-    _find_uses_recursive(node, source_code, uses)
-    return uses
-
-
-def _find_uses_recursive(node, source_code: bytes, uses: list):
-    """Recursively find use declarations."""
-    if node.type == "call":
-        target = None
-        arguments = None
-
-        for child in node.children:
-            if child.type == "identifier":
-                target = child
-            elif child.type == "arguments":
-                arguments = child
-
-        if target and arguments:
-            target_text = source_code[target.start_byte : target.end_byte].decode("utf-8")
 
-            if target_text == "use":
-                # Parse the use
-                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"
-                        )
-                        uses.append(module_name)
-
-    # Recursively search children, but skip function bodies
-    for child in node.children:
-        if child.type == "call":
-            is_function_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 ["def", "defp", "defmodule"]:
-                        is_function_def = True
-                        break
+    uses = []
 
-            if is_function_def:
-                continue
+    _find_declarations_recursive(node, source_code, uses, "use")
 
-        _find_uses_recursive(child, source_code, uses)
+    return uses
 
 
 def extract_behaviours(node, source_code: bytes) -> list:
@@ -288,62 +188,44 @@ def extract_behaviours(node, source_code: bytes) -> list:
     return behaviours
 
 
+def _parse_behaviour_call(node, source_code: bytes) -> str | None:
+    """Parse a behaviour call and return the module name."""
+    # Check if this is an @ operator with behaviour
+    is_at_operator = False
+    behaviour_call = None
+
+    for child in node.children:
+        if child.type == "@":
+            is_at_operator = True
+        elif child.type == "call" and is_at_operator:
+            behaviour_call = child
+            break
+
+    if behaviour_call:
+        # Check if the call is "behaviour"
+        identifier_text = None
+        arguments_node = None
+
+        for child in behaviour_call.children:
+            if child.type == "identifier":
+                identifier_text = extract_text_from_node(child, source_code)
+            elif child.type == "arguments":
+                arguments_node = child
+
+        if identifier_text == "behaviour" and arguments_node:
+            # Extract the behaviour module name
+            for arg_child in arguments_node.children:
+                if arg_child.type == "alias":
+                    # @behaviour ModuleName
+                    return extract_text_from_node(arg_child, source_code)
+                elif arg_child.type == "atom":
+                    # @behaviour :module_name
+                    atom_text = extract_text_from_node(arg_child, source_code)
+                    # Remove leading colon and convert to module format if needed
+                    return atom_text.lstrip(":")
+    return None
+
+
 def _find_behaviours_recursive(node, source_code: bytes, behaviours: list):
     """Recursively find @behaviour declarations."""
-    if node.type == "unary_operator":
-        # Check if this is an @ operator with behaviour
-        is_at_operator = False
-        behaviour_call = None
-
-        for child in node.children:
-            if child.type == "@":
-                is_at_operator = True
-            elif child.type == "call" and is_at_operator:
-                behaviour_call = child
-                break
-
-        if behaviour_call:
-            # Check if the call is "behaviour"
-            identifier_text = None
-            arguments_node = None
-
-            for child in behaviour_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 == "behaviour" and arguments_node:
-                # Extract the behaviour module name
-                for arg_child in arguments_node.children:
-                    if arg_child.type == "alias":
-                        # @behaviour ModuleName
-                        module_name = source_code[arg_child.start_byte : arg_child.end_byte].decode(
-                            "utf-8"
-                        )
-                        behaviours.append(module_name)
-                    elif arg_child.type == "atom":
-                        # @behaviour :module_name
-                        atom_text = source_code[arg_child.start_byte : arg_child.end_byte].decode(
-                            "utf-8"
-                        )
-                        # Remove leading colon and convert to module format if needed
-                        behaviours.append(atom_text.lstrip(":"))
-
-    # Recursively search children, but skip function bodies
-    for child in node.children:
-        if child.type == "call":
-            is_function_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 ["def", "defp", "defmodule"]:
-                        is_function_def = True
-                        break
-
-            if is_function_def:
-                continue
-
-        _find_behaviours_recursive(child, source_code, behaviours)
+    _find_nodes_recursive(node, source_code, behaviours, "unary_operator", _parse_behaviour_call)

cicada/extractors/doc.py

@@ -5,63 +5,16 @@ Documentation extraction logic.
 import textwrap
 
 from .base import extract_string_from_arguments
+from .common import _find_attribute_recursive
 
 
 def extract_docs(node, source_code: bytes) -> dict:
     """Extract all @doc attributes from a module body."""
     docs = {}
-    _find_docs_recursive(node, source_code, docs)
+    _find_attribute_recursive(node, source_code, docs, "doc", _parse_doc)
     return docs
 
 
-def _find_docs_recursive(node, source_code: bytes, docs: dict):
-    """Recursively find @doc 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 = source_code[call_child.start_byte : call_child.end_byte].decode(
-                        "utf-8"
-                    )
-
-                    if attr_name == "doc":
-                        # Extract the doc definition
-                        doc_info = _parse_doc(operand, source_code, node.start_point[0] + 1)
-                        if doc_info:
-                            # Store the entire doc_info dict (includes text and examples)
-                            docs[doc_info["line"]] = doc_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_docs_recursive(child, source_code, docs)
-
-
 def _parse_doc(doc_node, source_code: bytes, line: int) -> dict | None:
     """Parse a @doc attribute to extract its text and examples."""
     # @doc is represented as: doc("text") or doc(false)

cicada/extractors/function.py

@@ -4,6 +4,8 @@ Function extraction logic.
 Author: Cursor(Auto)
 """
 
+from cicada.utils import extract_text_from_node
+
 from .base import get_param_name
 
 
@@ -46,7 +48,7 @@ def _extract_impl_from_prev_sibling(node, source_code: bytes):
 
     for child in impl_call.children:
         if child.type == "identifier":
-            identifier_text = source_code[child.start_byte : child.end_byte].decode("utf-8")
+            identifier_text = extract_text_from_node(child, source_code)
         elif child.type == "arguments":
             arguments_node = child
 
@@ -58,11 +60,11 @@ def _extract_impl_from_prev_sibling(node, source_code: bytes):
         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")
+                bool_text = extract_text_from_node(arg_child, source_code)
                 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")
+                module_name = extract_text_from_node(arg_child, source_code)
                 return module_name
 
     # @impl without arguments defaults to true
@@ -90,7 +92,7 @@ def _find_functions_recursive(node, source_code: bytes, functions: list):
 
             # 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")
+                target_text = extract_text_from_node(target, source_code)
 
                 if target_text in ["def", "defp"]:
                     # Check if previous sibling is @impl
@@ -133,9 +135,7 @@ def _parse_function_definition(
             # 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"
-                    )
+                    func_name = extract_text_from_node(call_child, source_code)
                 elif call_child.type == "arguments":
                     arg_names = _extract_argument_names(call_child, source_code)
                     arity = len(arg_names)
@@ -148,16 +148,14 @@ def _parse_function_definition(
                     # 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")
+                            func_name = extract_text_from_node(call_child, source_code)
                         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")
+            func_name = extract_text_from_node(arg_child, source_code)
             arity = 0
             arg_names = []
             break
@@ -209,9 +207,7 @@ def _extract_guards(arguments_node, source_code: bytes) -> list[str]:
                 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"
-                    )
+                    guard_expr = extract_text_from_node(op_child, source_code)
                     guards.append(guard_expr)
                     break