cicada-mcp 0.1.4__py3-none-any.whl

cicada/extractors/dependency.py

@@ -0,0 +1,361 @@
+"""
+Dependency extraction logic (alias, import, require, use).
+
+Author: Cursor(Auto)
+"""
+
+
+def extract_aliases(node, source_code: bytes) -> dict:
+    """Extract all alias declarations from a module body."""
+    aliases = {}
+    _find_aliases_recursive(node, source_code, aliases)
+    return aliases
+
+
+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
+
+        if target and arguments:
+            target_text = source_code[target.start_byte : target.end_byte].decode(
+                "utf-8"
+            )
+
+            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)
+
+    # 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_aliases_recursive(child, source_code, aliases)
+
+
+def _parse_alias(arguments_node, source_code: bytes) -> dict | None:
+    """
+    Parse an alias declaration.
+
+    Handles:
+    - alias MyApp.User -> {User: MyApp.User}
+    - alias MyApp.User, as: U -> {U: MyApp.User}
+    - alias MyApp.{User, Post} -> {User: MyApp.User, Post: MyApp.Post}
+    """
+    result = {}
+
+    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"
+            )
+            # Get the last part as the short name
+            short_name = full_name.split(".")[-1]
+            result[short_name] = full_name
+
+        # Alias with tuple: alias MyApp.{User, Post}
+        elif arg_child.type == "dot":
+            # The dot node contains: alias (module prefix), dot, and tuple
+            module_prefix = None
+            tuple_node = 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")
+                elif dot_child.type == "tuple":
+                    tuple_node = dot_child
+
+            if module_prefix and tuple_node:
+                # 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")
+                        full_name = f"{module_prefix}.{short_name}"
+                        result[short_name] = full_name
+
+        # Keyword list for 'as:' option
+        elif arg_child.type == "keywords":
+            # Find the 'as:' keyword
+            for kw_child in arg_child.children:
+                if kw_child.type == "pair":
+                    key_text = None
+                    alias_name = 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")
+                        elif pair_child.type == "alias":
+                            alias_name = source_code[
+                                pair_child.start_byte : pair_child.end_byte
+                            ].decode("utf-8")
+
+                    # 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")
+                                # Remove the default short name and add custom one
+                                result.clear()
+                                result[alias_name] = full_name
+                                break
+
+    return result if result else 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
+
+
+def _find_imports_recursive(node, source_code: bytes, imports: list):
+    """Recursively find import 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 == "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
+
+        _find_imports_recursive(child, source_code, imports)
+
+
+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
+
+            if is_function_def:
+                continue
+
+        _find_requires_recursive(child, source_code, 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
+
+            if is_function_def:
+                continue
+
+        _find_uses_recursive(child, source_code, uses)
+
+
+def extract_behaviours(node, source_code: bytes) -> list:
+    """Extract all @behaviour declarations from a module body."""
+    behaviours = []
+    _find_behaviours_recursive(node, source_code, behaviours)
+    return behaviours
+
+
+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)

cicada/extractors/doc.py

@@ -0,0 +1,179 @@
+"""
+Documentation extraction logic.
+"""
+
+import textwrap
+from .base import extract_string_from_arguments
+
+
+def extract_docs(node, source_code: bytes) -> dict:
+    """Extract all @doc attributes from a module body."""
+    docs = {}
+    _find_docs_recursive(node, source_code, docs)
+    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)
+    for child in doc_node.children:
+        if child.type == "arguments":
+            doc_text = extract_string_from_arguments(child, source_code)
+            if doc_text:
+                # Extract examples section if present
+                doc_without_examples, examples = _extract_examples_from_doc(doc_text)
+                result = {"line": line, "text": doc_without_examples}
+                if examples:
+                    result["examples"] = examples
+                return result
+    return None
+
+
+def _extract_examples_from_doc(doc_text: str) -> tuple[str, str | None]:
+    """
+    Extract the ## Examples or # Examples section from doc text.
+
+    Args:
+        doc_text: The full @doc text
+
+    Returns:
+        Tuple of (doc_without_examples, examples_text)
+    """
+    import re
+
+    # Look for ## Examples or # Examples heading (case-insensitive)
+    # Match at the start of a line, possibly preceded by whitespace
+    examples_pattern = r"^\s*#{1,2}\s+Examples?\s*$"
+
+    lines = doc_text.split("\n")
+    examples_start_idx = None
+
+    # Find the line where examples section starts
+    for i, line in enumerate(lines):
+        if re.match(examples_pattern, line, re.IGNORECASE):
+            examples_start_idx = i
+            break
+
+    # If no examples section found, return original doc with dedent
+    if examples_start_idx is None:
+        return textwrap.dedent(doc_text), None
+
+    # Find where examples section ends (next ## heading or end of doc)
+    examples_end_idx = len(lines)
+    for i in range(examples_start_idx + 1, len(lines)):
+        # Check if this line is another top-level heading (##)
+        if re.match(r"^\s*##\s+\w+", lines[i]):
+            examples_end_idx = i
+            break
+
+    # Extract the parts
+    doc_lines = lines[:examples_start_idx]
+    examples_lines = lines[examples_start_idx:examples_end_idx]
+    remaining_lines = lines[examples_end_idx:]
+
+    # Reconstruct doc without examples
+    doc_without_examples = "\n".join(doc_lines + remaining_lines).strip()
+
+    # Dedent the doc text
+    if doc_without_examples:
+        doc_without_examples = textwrap.dedent(doc_without_examples)
+
+    # Extract just the examples content (without the heading)
+    if len(examples_lines) <= 1:
+        return doc_without_examples, None
+
+    examples_lines_content = examples_lines[1:]
+
+    # Find minimum indentation from non-empty lines
+    min_indent: int | float = float("inf")
+    for line in examples_lines_content:
+        if line.strip():  # Skip blank lines
+            indent = len(line) - len(line.lstrip())
+            min_indent = min(min_indent, indent)
+
+    # Remove the common indentation from all lines
+    if min_indent < float("inf"):
+        dedented_lines: list[str] = []
+        min_indent_int = int(min_indent)
+        for line in examples_lines_content:
+            if line.strip():  # Non-empty line
+                dedented_lines.append(line[min_indent_int:])
+            else:  # Empty line
+                dedented_lines.append(line)
+        examples_content = "\n".join(dedented_lines).strip()
+    else:
+        examples_content = "\n".join(examples_lines_content).strip()
+
+    return doc_without_examples, examples_content if examples_content else None
+
+
+def match_docs_to_functions(functions: list, docs: dict):
+    """Match @doc attributes to functions based on proximity."""
+    # @doc appears before the function, possibly with @spec in between
+    # Look back up to 50 lines to handle long docs and @spec attributes
+    for func in functions:
+        func_line = func["line"]
+        # Look for @doc in the lines before the function (up to 50 lines)
+        for offset in range(1, 51):
+            doc_line = func_line - offset
+            if doc_line in docs:
+                # docs[doc_line] is now a dict with 'text' and optionally 'examples'
+                doc_info = docs[doc_line]
+                if isinstance(doc_info, dict):
+                    func["doc"] = doc_info.get("text")
+                    if "examples" in doc_info:
+                        func["examples"] = doc_info["examples"]
+                else:
+                    # Backward compatibility: if it's just a string
+                    func["doc"] = doc_info
+                break