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

cicada/setup.py

@@ -22,7 +22,7 @@ from cicada.utils import (
     get_index_path,
 )
 
-EditorType = Literal["claude", "cursor", "vs"]
+EditorType = Literal["claude", "cursor", "vs", "gemini", "codex"]
 
 
 def _load_existing_config(config_path: Path) -> dict:
@@ -74,7 +74,6 @@ def _build_server_config(
         server_config["cwd"] = cwd
 
     server_config["env"] = {
-        "CICADA_REPO_PATH": str(repo_path),
         "CICADA_CONFIG_DIR": str(storage_dir),
     }
 
@@ -118,6 +117,16 @@ def get_mcp_config_for_editor(
             "config_key": "mcp.servers",
             "needs_dir": True,
         },
+        "gemini": {
+            "config_path": repo_path / ".gemini" / "mcp.json",
+            "config_key": "mcpServers",
+            "needs_dir": True,
+        },
+        "codex": {
+            "config_path": repo_path / ".codex" / "mcp.json",
+            "config_key": "mcpServers",
+            "needs_dir": True,
+        },
     }
 
     if editor not in editor_specs:
@@ -147,8 +156,8 @@ def get_mcp_config_for_editor(
 def create_config_yaml(
     repo_path: Path,
     storage_dir: Path,
-    keyword_method: str | None = None,
-    keyword_tier: str | None = None,
+    extraction_method: str | None = None,
+    expansion_method: str | None = None,
     verbose: bool = True,
 ) -> None:
     """
@@ -157,18 +166,18 @@ def create_config_yaml(
     Args:
         repo_path: Path to the repository
         storage_dir: Path to the storage directory
-        keyword_method: Keyword extraction method ('lemminflect' or 'bert'), None for default
-        keyword_tier: Model tier ('fast', 'regular', 'max'), None for default
+        extraction_method: Keyword extraction method ('regular' or 'bert'), None for default
+        expansion_method: Expansion method ('lemmi', 'glove', or 'fasttext'), None for default
         verbose: If True, print success message. If False, silently create config.
     """
     config_path = get_config_path(repo_path)
     index_path = get_index_path(repo_path)
 
-    # Default to lemminflect if not specified
-    if keyword_method is None:
-        keyword_method = "lemminflect"
-    if keyword_tier is None:
-        keyword_tier = "regular"
+    # Default to regular extraction + lemmi expansion
+    if extraction_method is None:
+        extraction_method = "regular"
+    if expansion_method is None:
+        expansion_method = "lemmi"
 
     config_content = f"""repository:
   path: {repo_path}
@@ -177,8 +186,10 @@ storage:
   index_path: {index_path}
 
 keyword_extraction:
-  method: {keyword_method}
-  tier: {keyword_tier}
+  method: {extraction_method}
+
+keyword_expansion:
+  method: {expansion_method}
 """
 
     with open(config_path, "w") as f:
@@ -249,11 +260,118 @@ def setup_multiple_editors(
                 print(f"⚠ Error creating {editor.upper()} config: {e}")
 
 
+def update_claude_md(repo_path: Path, editor: EditorType | None = None) -> None:
+    """Update CLAUDE.md and AGENTS.md with instructions to use cicada-mcp for Elixir codebase searches.
+
+    Args:
+        repo_path: Path to the repository
+        editor: Editor type - defaults to None which updates CLAUDE.md (for backward compatibility)
+    """
+    from cicada.mcp.tools import get_tool_definitions
+
+    claude_md_path = repo_path / "CLAUDE.md"
+    agents_md_path = repo_path / "AGENTS.md"
+
+    # Process CLAUDE.md if no editor specified (backward compatibility) or if editor is 'claude'
+    if (editor is None or editor == "claude") and claude_md_path.exists():
+        _update_md_file(claude_md_path, get_tool_definitions())
+
+    # Process AGENTS.md for all editors if it exists (when editor is specified)
+    if editor is not None and agents_md_path.exists():
+        _update_md_file(agents_md_path, get_tool_definitions())
+
+
+def _update_md_file(md_path: Path, tools) -> None:
+    """Update a markdown file with cicada tool instructions.
+
+    Args:
+        md_path: Path to the markdown file (CLAUDE.md or AGENTS.md)
+        tools: Tool definitions from get_tool_definitions()
+    """
+    import re
+
+    # Auto-generate tool list from tools
+    tool_list: list[str] = []
+
+    for tool in tools:
+        # Skip deprecated tools
+        if tool.description and "DEPRECATED" in tool.description:
+            continue
+
+        # Extract first sentence from description (up to first period or newline)
+        if tool.description:
+            desc = tool.description.split("\n")[0].strip()
+            if "." in desc:
+                desc = desc.split(".")[0] + "."
+            line = f"  - {desc} `mcp__cicada__{tool.name}`"
+            tool_list.append(line)
+
+    tool_list_str = "\n".join(tool_list)
+
+    # Identify the categories of tools
+    grep_antipatterns = [
+        "  - ❌ Searching for module structure",
+        "  - ❌ Searching for function definitions",
+        "  - ❌ Searching for module imports/usage",
+    ]
+    grep_antipatterns_str = "\n".join(grep_antipatterns)
+
+    instruction_content = f"""<cicada>
+  **ALWAYS use cicada-mcp tools for Elixir code searches. NEVER use Grep/Find for these tasks.**
+
+  ### Use cicada tools for:
+{tool_list_str}
+
+  ### DO NOT use Grep for:
+{grep_antipatterns_str}
+
+  ### You can still use Grep for:
+  - ✓ Non-code files (markdown, JSON, config)
+  - ✓ String literal searches
+  - ✓ Pattern matching in single line comments
+</cicada>
+"""
+
+    try:
+        # Read existing content
+        with open(md_path) as f:
+            content = f.read()
+
+        # Pattern to find existing <cicada>...</cicada> tags
+        cicada_pattern = re.compile(r"<cicada>.*?</cicada>", re.DOTALL)
+
+        # Check if <cicada> tags exist
+        if cicada_pattern.search(content):
+            # Replace existing content between tags
+            new_content = cicada_pattern.sub(instruction_content, content)
+            with open(md_path, "w") as f:
+                f.write(new_content)
+            print(f"✓ Updated <cicada> instructions in {md_path.name}")
+        elif "cicada-mcp" in content.lower() or "cicada" in content.lower():
+            # Content already mentions cicada, don't add duplication
+            # This handles cases where users manually added cicada instructions
+            print(f"✓ {md_path.name} already mentions cicada, skipping update")
+        else:
+            # Append the instruction
+            with open(md_path, "a") as f:
+                # Add newline if file doesn't end with one
+                if content and not content.endswith("\n"):
+                    f.write("\n")
+
+                f.write("\n")
+                f.write(instruction_content)
+
+            print(f"✓ Added cicada-mcp usage instructions to {md_path.name}")
+    except Exception:
+        # Fail silently on any errors
+        pass
+
+
 def setup(
     editor: EditorType,
     repo_path: Path | None = None,
-    keyword_method: str | None = None,
-    keyword_tier: str | None = None,
+    extraction_method: str | None = None,
+    expansion_method: str | None = None,
     index_exists: bool = False,
 ) -> None:
     """
@@ -262,8 +380,8 @@ def setup(
     Args:
         editor: Editor type (claude, cursor, vs)
         repo_path: Path to the repository (defaults to current directory)
-        keyword_method: Keyword extraction method ('lemminflect' or 'bert'), None for default
-        keyword_tier: Model tier ('fast', 'regular', 'max'), None for default
+        extraction_method: Keyword extraction method ('regular' or 'bert'), None for default
+        expansion_method: Expansion method ('lemmi', 'glove', or 'fasttext'), None for default
         index_exists: If True, skip banner and show condensed output (index already exists)
     """
     # Determine repository path
@@ -276,15 +394,19 @@ def setup(
 
     # Show condensed output if index already exists
     if index_exists:
-        # Determine method and tier for display
-        display_method = keyword_method if keyword_method else "lemminflect"
-        display_tier = keyword_tier if keyword_tier else "regular"
-        print(f"✓ Found existing index ({display_method.upper()} {display_tier})")
+        # Determine method for display
+        display_extraction = extraction_method if extraction_method else "regular"
+        display_expansion = expansion_method if expansion_method else "lemmi"
+        print(
+            f"✓ Found existing index ({display_extraction.upper()} + {display_expansion.upper()})"
+        )
         # Skip indexing when index_exists is True - we're just reusing it
         should_index = False
         force_full = False
         # Ensure config.yaml is up to date with current settings
-        create_config_yaml(repo_path, storage_dir, keyword_method, keyword_tier, verbose=False)
+        create_config_yaml(
+            repo_path, storage_dir, extraction_method, expansion_method, verbose=False
+        )
     else:
         # Show full banner for new setup
         print("=" * 60)
@@ -307,20 +429,20 @@ def setup(
             try:
                 with open(config_path) as f:
                     existing_config = yaml.safe_load(f)
-                    existing_method = existing_config.get("keyword_extraction", {}).get(
-                        "method", "lemminflect"
+                    existing_extraction = existing_config.get("keyword_extraction", {}).get(
+                        "method", "regular"
                     )
-                    existing_tier = existing_config.get("keyword_extraction", {}).get(
-                        "tier", "regular"
+                    existing_expansion = existing_config.get("keyword_expansion", {}).get(
+                        "method", "lemmi"
                     )
 
-                    # Determine new method and tier (default to lemminflect/regular if not specified)
-                    new_method = keyword_method if keyword_method else "lemminflect"
-                    new_tier = keyword_tier if keyword_tier else "regular"
+                    # Determine new methods (default to regular + lemmi if not specified)
+                    new_extraction = extraction_method if extraction_method else "regular"
+                    new_expansion = expansion_method if expansion_method else "lemmi"
 
                     # Check if settings changed
-                    settings_changed = (existing_method != new_method) or (
-                        existing_tier != new_tier
+                    settings_changed = (existing_extraction != new_extraction) or (
+                        existing_expansion != new_expansion
                     )
 
                     if settings_changed:
@@ -329,9 +451,11 @@ def setup(
                         print("=" * 60)
                         print()
                         print(
-                            f"This repository already has an index with {existing_method.upper()} ({existing_tier}) keyword extraction."
+                            f"This repository already has an index with {existing_extraction.upper()} + {existing_expansion.upper()}."
+                        )
+                        print(
+                            f"You are now switching to {new_extraction.upper()} + {new_expansion.upper()}."
                         )
-                        print(f"You are now switching to {new_method.upper()} ({new_tier}).")
                         print()
                         print(
                             "This will require reindexing the ENTIRE codebase, which may take several minutes."
@@ -347,7 +471,9 @@ def setup(
                         force_full = True  # Force full reindex when settings change
                     else:
                         # Settings unchanged - just use existing index
-                        print(f"✓ Using existing index ({existing_method}, {existing_tier})")
+                        print(
+                            f"✓ Using existing index ({existing_extraction.upper()} + {existing_expansion.upper()})"
+                        )
                         print()
                         should_index = False
             except Exception:
@@ -355,13 +481,19 @@ def setup(
                 pass
 
         # Create/update config.yaml BEFORE indexing (indexer reads this to determine keyword method)
-        create_config_yaml(repo_path, storage_dir, keyword_method, keyword_tier, verbose=False)
+        create_config_yaml(
+            repo_path, storage_dir, extraction_method, expansion_method, verbose=False
+        )
 
         # Index repository if needed
         if should_index:
             index_repository(repo_path, force_full=force_full)
             print()
 
+    # Update CLAUDE.md with cicada instructions (only for Claude Code editor)
+    if editor == "claude":
+        update_claude_md(repo_path)
+
     # Create MCP config for the editor
     config_path, config_content = get_mcp_config_for_editor(editor, repo_path, storage_dir)
 

cicada/tier.py

@@ -0,0 +1,225 @@
+"""
+Tier Configuration Module - Centralized tier resolution and conversion logic.
+
+This module provides a single source of truth for:
+- Tier validation (fast, regular, max)
+- Tier resolution from arguments or config files
+- Tier <-> (extraction_method, expansion_method) conversions
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+# Tier to methods mapping
+TIER_METHODS = {
+    "fast": ("regular", "lemmi"),
+    "regular": ("bert", "glove"),
+    "max": ("bert", "fasttext"),
+}
+
+# Default methods if no configuration exists
+DEFAULT_METHODS = ("regular", "lemmi")
+
+
+def validate_tier_flags(args: argparse.Namespace, *, require_force: bool = False) -> None:
+    """Validate that only one tier flag is specified.
+
+    Args:
+        args: Parsed command-line arguments with fast, regular, and max attributes
+        require_force: Whether --force is required when specifying tier flags
+
+    Raises:
+        SystemExit: If validation fails
+    """
+    tier_flags = [bool(args.fast), bool(getattr(args, "regular", False)), bool(args.max)]
+    tier_count = sum(tier_flags)
+
+    if tier_count > 1:
+        print(
+            "Error: Can only specify one tier flag (--fast, --regular, or --max)",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if not require_force:
+        return
+
+    force_enabled = getattr(args, "force", False) is True
+    tier_specified = tier_count == 1
+
+    if force_enabled and not tier_specified:
+        print(
+            "Error: --force requires specifying a tier flag (--fast, --regular, or --max).",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    if tier_specified and not force_enabled:
+        print(
+            "Error: Tier flags now require --force to override the configured tier.",
+            file=sys.stderr,
+        )
+        print(
+            "Run 'cicada index --force --fast|--regular|--max' to select a tier.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+
+def tier_flag_specified(args: argparse.Namespace) -> bool:
+    """Return True when any tier flag is present."""
+    return bool(args.fast or getattr(args, "regular", False) or args.max)
+
+
+def get_tier_from_args(args: argparse.Namespace) -> str | None:
+    """Extract tier from command-line arguments.
+
+    Args:
+        args: Parsed command-line arguments with fast, regular, and max attributes
+
+    Returns:
+        Tier string ("fast", "regular", or "max"), or None if no tier flag specified
+    """
+    if args.fast:
+        return "fast"
+    if args.max:
+        return "max"
+    if getattr(args, "regular", False):
+        return "regular"
+    return None
+
+
+def tier_to_methods(tier: str) -> tuple[str, str]:
+    """Convert tier to (extraction_method, expansion_method).
+
+    Args:
+        tier: Tier string ("fast", "regular", or "max")
+
+    Returns:
+        Tuple of (extraction_method, expansion_method)
+        - extraction_method is 'regular' or 'bert'
+        - expansion_method is 'lemmi', 'glove', or 'fasttext'
+
+    Tier mappings:
+        - fast: regular extraction + lemmi expansion
+        - regular: bert extraction + glove expansion
+        - max: bert extraction + fasttext expansion
+    """
+    return TIER_METHODS.get(tier, DEFAULT_METHODS)
+
+
+def methods_to_tier(extraction_method: str, expansion_method: str) -> str:
+    """Convert (extraction_method, expansion_method) to tier.
+
+    Args:
+        extraction_method: 'regular' or 'bert'
+        expansion_method: 'lemmi', 'glove', or 'fasttext'
+
+    Returns:
+        Tier string: "fast", "regular", or "max"
+    """
+    method_pair = (extraction_method, expansion_method)
+
+    # Find matching tier in our mapping
+    for tier, methods in TIER_METHODS.items():
+        if methods == method_pair:
+            return tier
+
+    # Fallback logic for partial matches
+    if extraction_method == "regular":
+        return "fast"
+
+    if extraction_method == "bert":
+        if expansion_method == "fasttext":
+            return "max"
+        return "regular"
+
+    # Default to regular for unknown combinations
+    return "regular"
+
+
+def read_keyword_extraction_config(repo_path: Path) -> tuple[str, str]:
+    """Read keyword extraction configuration from config.yaml.
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        tuple[str, str]: (extraction_method, expansion_method) where:
+                        - extraction_method is 'regular' or 'bert'
+                        - expansion_method is 'lemmi', 'glove', or 'fasttext'
+                        Returns DEFAULT_METHODS if config not found.
+    """
+    try:
+        import yaml
+
+        from cicada.utils.storage import get_config_path
+
+        config_path = get_config_path(repo_path)
+        if not config_path.exists():
+            return DEFAULT_METHODS
+
+        with open(config_path) as f:
+            config = yaml.safe_load(f)
+
+        if not config:
+            return DEFAULT_METHODS
+
+        extraction_method = config.get("keyword_extraction", {}).get("method", DEFAULT_METHODS[0])
+        expansion_method = config.get("keyword_expansion", {}).get("method", DEFAULT_METHODS[1])
+        return (extraction_method, expansion_method)
+
+    except Exception:
+        # If anything goes wrong, use defaults
+        return DEFAULT_METHODS
+
+
+def determine_tier(args: argparse.Namespace, repo_path: Path | None = None) -> str:
+    """Determine indexing tier from args or existing config.
+
+    This is the main function for tier resolution. It:
+    1. Checks command-line arguments first (--fast, --regular, --max)
+    2. Falls back to reading from config.yaml if no args provided
+    3. Defaults to "regular" if no config found
+
+    Args:
+        args: Parsed command-line arguments with fast, regular, and max attributes
+        repo_path: Optional repository path to read config from
+
+    Returns:
+        Tier string: "fast", "regular", or "max"
+    """
+    # Check args first
+    tier = get_tier_from_args(args)
+    if tier is not None:
+        return tier
+
+    # If no tier flag specified, try to load from existing config
+    if repo_path is not None:
+        extraction_method, expansion_method = read_keyword_extraction_config(repo_path)
+        return methods_to_tier(extraction_method, expansion_method)
+
+    # Default to regular tier
+    return "regular"
+
+
+def get_extraction_expansion_methods(
+    args: argparse.Namespace,
+) -> tuple[str | None, str | None]:
+    """Map tier flags to extraction and expansion methods.
+
+    This is a convenience function for backward compatibility.
+    Returns (None, None) if no tier flag is specified, allowing callers
+    to distinguish between "no tier specified" and "default tier".
+
+    Args:
+        args: Parsed command-line arguments with fast, regular, and max attributes
+
+    Returns:
+        Tuple of (extraction_method, expansion_method), or (None, None) if no tier flag
+    """
+    tier = get_tier_from_args(args)
+    if tier is None:
+        return None, None
+    return tier_to_methods(tier)

cicada/utils/__init__.py

@@ -7,13 +7,14 @@ code duplication and improve maintainability.
 
 from .call_site_formatter import CallSiteFormatter
 from .function_grouper import FunctionGrouper
+from .fuzzy_match import find_similar_names
 from .index_utils import (
     load_index,
     merge_indexes_incremental,
     save_index,
     validate_index_structure,
 )
-from .path_utils import normalize_file_path, resolve_to_repo_root
+from .path_utils import is_git_repository, normalize_file_path, resolve_to_repo_root
 from .signature_builder import SignatureBuilder
 from .storage import (
     create_storage_dir,
@@ -25,7 +26,8 @@ from .storage import (
     get_storage_dir,
 )
 from .subprocess_runner import SubprocessRunner, run_gh_command, run_git_command
-from .text_utils import split_camel_snake_case, split_identifier
+from .text_utils import extract_code_identifiers, split_camel_snake_case, split_identifier
+from .tree_utils import extract_text_from_node, is_function_definition_call
 
 __all__ = [
     "SubprocessRunner",
@@ -33,6 +35,7 @@ __all__ = [
     "run_gh_command",
     "normalize_file_path",
     "resolve_to_repo_root",
+    "is_git_repository",
     "load_index",
     "save_index",
     "merge_indexes_incremental",
@@ -40,8 +43,10 @@ __all__ = [
     "FunctionGrouper",
     "CallSiteFormatter",
     "SignatureBuilder",
+    "find_similar_names",
     "split_identifier",
     "split_camel_snake_case",
+    "extract_code_identifiers",
     "get_repo_hash",
     "get_storage_dir",
     "create_storage_dir",
@@ -49,4 +54,6 @@ __all__ = [
     "get_config_path",
     "get_hashes_path",
     "get_pr_index_path",
+    "extract_text_from_node",
+    "is_function_definition_call",
 ]

cicada/utils/fuzzy_match.py

@@ -0,0 +1,54 @@
+"""
+Fuzzy matching utilities for finding similar names.
+
+This module provides utilities for finding similar module and function names
+using fuzzy string matching algorithms.
+"""
+
+from difflib import SequenceMatcher
+
+
+def find_similar_names(
+    query: str, candidates: list[str], max_suggestions: int = 5, threshold: float = 0.4
+) -> list[tuple[str, float]]:
+    """
+    Find similar names using fuzzy matching.
+
+    Args:
+        query: The query string to match
+        candidates: List of candidate names to match against
+        max_suggestions: Maximum number of suggestions to return
+        threshold: Minimum similarity score (0.0-1.0) to include in results
+
+    Returns:
+        List of (name, similarity_score) tuples, sorted by similarity (descending)
+    """
+    similarities: list[tuple[str, float]] = []
+    query_lower = query.lower()
+
+    # Early exit for exact match
+    for candidate in candidates:
+        if query_lower == candidate.lower():
+            return [(candidate, 1.0)]
+
+    # Limit search space for very large indices to prevent performance issues
+    search_candidates = candidates[:500] if len(candidates) > 500 else candidates
+
+    for candidate in search_candidates:
+        # Calculate base similarity score
+        similarity = SequenceMatcher(None, query_lower, candidate.lower()).ratio()
+
+        # Boost score for substring matches
+        if query_lower in candidate.lower():
+            similarity = max(similarity, 0.7)
+
+        # Boost score for partial component matches (e.g., "User" matches "MyApp.User")
+        query_parts = query.split(".")
+        if any(qpart.lower() in candidate.lower() for qpart in query_parts):
+            similarity = max(similarity, 0.6)
+
+        similarities.append((candidate, similarity))
+
+    # Sort by similarity (descending) and return top matches above threshold
+    similarities.sort(key=lambda x: x[1], reverse=True)
+    return [(name, score) for name, score in similarities[:max_suggestions] if score > threshold]

cicada/utils/index_utils.py

@@ -274,12 +274,21 @@ def merge_indexes_incremental(
     if "modules" in new_index:
         merged["modules"].update(new_index["modules"])
 
+    # Preserve original cicada_version from old_index if it exists
+    original_version = None
+    if "metadata" in old_index:
+        original_version = old_index["metadata"].get("cicada_version")
+
     # Merge metadata - take from new_index if available, else old_index
     if "metadata" in new_index:
         merged["metadata"].update(new_index["metadata"])
     elif "metadata" in old_index:
         merged["metadata"].update(old_index["metadata"])
 
+    # Restore original version if it existed (don't overwrite with new version)
+    if original_version:
+        merged["metadata"]["cicada_version"] = original_version
+
     # Update module and function counts
     stats = get_index_stats(merged)
     merged["metadata"]["total_modules"] = stats["total_modules"]