cicada-mcp 0.1.4__py3-none-any.whl

cicada/pr_indexer/pr_index_builder.py

@@ -0,0 +1,253 @@
+"""
+PR Index Builder.
+
+This module handles building and merging PR index structures,
+separating index construction logic from API and mapping concerns.
+"""
+
+from datetime import datetime
+from typing import Dict, List, Any, Optional
+
+from cicada.utils import load_index as load_index_util, save_index as save_index_util
+
+
+class PRIndexBuilder:
+    """
+    Builds and manages PR index structures.
+
+    This class handles creating, merging, and saving PR indexes,
+    keeping index manipulation separate from data fetching.
+    """
+
+    def __init__(self, repo_owner: str, repo_name: str):
+        """
+        Initialize the index builder.
+
+        Args:
+            repo_owner: GitHub repository owner
+            repo_name: GitHub repository name
+        """
+        self.repo_owner = repo_owner
+        self.repo_name = repo_name
+
+    def build_index(
+        self, prs: List[Dict[str, Any]], preserve_last_pr: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        Build the index structure from PR data.
+
+        Args:
+            prs: List of PR dictionaries
+            preserve_last_pr: If set, use this as last_pr_number instead of calculating.
+                             Used when building partial indexes from interrupted fetches.
+
+        Returns:
+            Index dictionary with metadata, prs, commit_to_pr mapping, and file_to_prs mapping
+        """
+        print("Building index...")
+
+        # Build commit -> PR mapping
+        commit_to_pr = self._build_commit_mapping(prs)
+
+        # Build file -> PRs mapping
+        file_to_prs = self._build_file_mapping(prs)
+
+        # Count total comments
+        total_comments = sum(len(pr.get("comments", [])) for pr in prs)
+
+        # Build index structure
+        metadata: Dict[str, Any] = {
+            "repo_owner": self.repo_owner,
+            "repo_name": self.repo_name,
+            "last_indexed_at": datetime.now().isoformat(),
+            "total_prs": len(prs),
+            "total_commits_mapped": len(commit_to_pr),
+            "total_comments": total_comments,
+            "total_files": len(file_to_prs),
+        }
+        index: Dict[str, Any] = {
+            "metadata": metadata,
+            "prs": {str(pr["number"]): pr for pr in prs},
+            "commit_to_pr": commit_to_pr,
+            "file_to_prs": file_to_prs,
+        }
+
+        # Track last PR number for incremental updates
+        if preserve_last_pr is not None:
+            # Use preserved value (for partial/interrupted fetches)
+            index["metadata"]["last_pr_number"] = preserve_last_pr
+        elif prs:
+            # Calculate from PRs (for complete fetches)
+            index["metadata"]["last_pr_number"] = max(pr["number"] for pr in prs)
+
+        print(
+            f"Index built: {len(prs)} PRs, {len(commit_to_pr)} commits, "
+            f"{len(file_to_prs)} files, {total_comments} comments"
+        )
+        return index
+
+    def _build_commit_mapping(self, prs: List[Dict[str, Any]]) -> Dict[str, int]:
+        """
+        Build commit SHA -> PR number mapping.
+
+        Args:
+            prs: List of PR dictionaries
+
+        Returns:
+            Dictionary mapping commit SHAs to PR numbers
+        """
+        commit_to_pr = {}
+        for pr in prs:
+            pr_number = pr["number"]
+            for commit in pr["commits"]:
+                commit_to_pr[commit] = pr_number
+        return commit_to_pr
+
+    def _build_file_mapping(self, prs: List[Dict[str, Any]]) -> Dict[str, List[int]]:
+        """
+        Build file path -> PR numbers mapping.
+
+        Args:
+            prs: List of PR dictionaries
+
+        Returns:
+            Dictionary mapping file paths to lists of PR numbers (sorted newest first)
+        """
+        file_to_prs = {}
+        for pr in prs:
+            pr_number = pr["number"]
+            for file_path in pr.get("files_changed", []):
+                if file_path not in file_to_prs:
+                    file_to_prs[file_path] = []
+                file_to_prs[file_path].append(pr_number)
+
+        # Sort PR numbers for each file (newest first)
+        for file_path in file_to_prs:
+            file_to_prs[file_path].sort(reverse=True)
+
+        return file_to_prs
+
+    def merge_indexes(
+        self, existing_index: Dict[str, Any], new_prs: List[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """
+        Merge new PRs into existing index.
+
+        Args:
+            existing_index: The existing index
+            new_prs: List of new PR dictionaries
+
+        Returns:
+            Updated index dictionary
+        """
+        print("Merging new PRs into existing index...")
+
+        # Update PR data
+        for pr in new_prs:
+            existing_index["prs"][str(pr["number"])] = pr
+
+            # Update commit -> PR mapping
+            for commit in pr["commits"]:
+                existing_index["commit_to_pr"][commit] = pr["number"]
+
+        # Rebuild file -> PRs mapping from scratch (most reliable)
+        file_to_prs = self._build_file_mapping(list(existing_index["prs"].values()))
+        existing_index["file_to_prs"] = file_to_prs
+
+        # Count total comments
+        total_comments = sum(
+            len(pr.get("comments", [])) for pr in existing_index["prs"].values()
+        )
+
+        # Update metadata
+        existing_index["metadata"]["last_indexed_at"] = datetime.now().isoformat()
+        existing_index["metadata"]["total_prs"] = len(existing_index["prs"])
+        existing_index["metadata"]["total_commits_mapped"] = len(
+            existing_index["commit_to_pr"]
+        )
+        existing_index["metadata"]["total_comments"] = total_comments
+        existing_index["metadata"]["total_files"] = len(file_to_prs)
+
+        # Update last_pr_number to the highest PR we have in the index
+        if existing_index["prs"]:
+            all_pr_numbers = [int(num) for num in existing_index["prs"].keys()]
+            existing_index["metadata"]["last_pr_number"] = max(all_pr_numbers)
+
+        return existing_index
+
+    def merge_partial_clean(
+        self, existing_index: Dict[str, Any], partial_index: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Merge a partial clean build with an existing index.
+
+        This is used when a --clean rebuild is interrupted. We want to keep both:
+        - PRs from the existing index (old data)
+        - PRs from the partial new index (newly fetched data)
+
+        Args:
+            existing_index: The old complete/partial index
+            partial_index: The new partial index from interrupted --clean
+
+        Returns:
+            Merged index with all PRs from both indexes
+        """
+        print("Merging partial index with existing index...")
+
+        # Start with existing index structure
+        merged = existing_index.copy()
+
+        # Update PRs: add/replace with new PRs from partial index
+        for pr_num_str, pr_data in partial_index["prs"].items():
+            merged["prs"][pr_num_str] = pr_data
+
+        # Rebuild commit -> PR mapping from scratch
+        merged["commit_to_pr"] = self._build_commit_mapping(
+            list(merged["prs"].values())
+        )
+
+        # Rebuild file -> PRs mapping from scratch
+        merged["file_to_prs"] = self._build_file_mapping(list(merged["prs"].values()))
+
+        # Count total comments
+        total_comments = sum(
+            len(pr.get("comments", [])) for pr in merged["prs"].values()
+        )
+
+        # Update metadata (use partial_index's last_pr_number which was preserved)
+        merged["metadata"]["last_indexed_at"] = datetime.now().isoformat()
+        merged["metadata"]["total_prs"] = len(merged["prs"])
+        merged["metadata"]["total_commits_mapped"] = len(merged["commit_to_pr"])
+        merged["metadata"]["total_comments"] = total_comments
+        merged["metadata"]["total_files"] = len(merged["file_to_prs"])
+        merged["metadata"]["last_pr_number"] = partial_index["metadata"].get(
+            "last_pr_number", 0
+        )
+
+        print(
+            f"Merged: {len(merged['prs'])} total PRs "
+            f"({len(partial_index['prs'])} new/updated)"
+        )
+        return merged
+
+    def load_existing_index(self, index_path: str) -> Optional[Dict[str, Any]]:
+        """
+        Load existing index file if it exists.
+
+        Args:
+            index_path: Path to the index file
+
+        Returns:
+            Existing index dictionary or None if file doesn't exist
+        """
+        return load_index_util(index_path, verbose=True, raise_on_error=False)
+
+    def save_index(self, index: Dict[str, Any], output_path: str) -> None:
+        """
+        Save index to file.
+
+        Args:
+            index: Index dictionary to save
+            output_path: Path where the index will be saved
+        """
+        save_index_util(index, output_path, create_dirs=True, verbose=True)

cicada/setup.py

@@ -0,0 +1,339 @@
+#!/usr/bin/env python
+"""
+Cicada Simplified Setup Script.
+
+One-command setup: uvx cicada [claude|cursor|vs]
+- Indexes the repository with keyword extraction
+- Stores all files in temp directory (~/.cicada/projects/<hash>/)
+- Creates only MCP config file in user's repo
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Literal
+
+from cicada.indexer import ElixirIndexer
+from cicada.utils import (
+    create_storage_dir,
+    get_index_path,
+    get_config_path,
+    get_hashes_path,
+    get_storage_dir,
+)
+
+
+EditorType = Literal["claude", "cursor", "vs"]
+
+
+def _load_existing_config(config_path: Path) -> dict:
+    """
+    Load existing configuration file with error handling.
+
+    Args:
+        config_path: Path to the config file
+
+    Returns:
+        Loaded config dict, or empty dict if file doesn't exist or is invalid
+    """
+    if not config_path.exists():
+        return {}
+
+    try:
+        with open(config_path, "r") as f:
+            return json.load(f)
+    except json.JSONDecodeError as e:
+        print(
+            f"Warning: Existing config at {config_path} is malformed, creating new one: {e}"
+        )
+        return {}
+    except IOError as e:
+        print(f"Warning: Could not read config file {config_path}: {e}")
+        return {}
+
+
+def _build_server_config(
+    command: str, args: list, cwd: str | None, repo_path: Path, storage_dir: Path
+) -> dict:
+    """
+    Build the MCP server configuration.
+
+    Args:
+        command: Command to run the MCP server
+        args: Command line arguments
+        cwd: Working directory (optional)
+        repo_path: Path to the repository
+        storage_dir: Path to the storage directory
+
+    Returns:
+        Server configuration dict
+    """
+    server_config = {"command": command}
+
+    if args:
+        server_config["args"] = args
+
+    if cwd:
+        server_config["cwd"] = cwd
+
+    server_config["env"] = {
+        "CICADA_REPO_PATH": str(repo_path),
+        "CICADA_CONFIG_DIR": str(storage_dir),
+    }
+
+    return server_config
+
+
+def get_mcp_config_for_editor(
+    editor: EditorType, repo_path: Path, storage_dir: Path
+) -> tuple[Path, dict]:
+    """
+    Get the MCP configuration file path and content for a specific editor.
+
+    Args:
+        editor: Editor type (claude, cursor, vs)
+        repo_path: Path to the repository
+        storage_dir: Path to the storage directory
+
+    Returns:
+        Tuple of (config_file_path, config_content)
+    """
+    # Detect installation method
+    import shutil
+
+    has_cicada_server = shutil.which("cicada-server") is not None
+
+    if has_cicada_server:
+        command = "cicada-server"
+        args = []
+        cwd = None
+    else:
+        python_bin = sys.executable
+        command = str(python_bin)
+        args = ["-m", "cicada.mcp_server"]
+        cwd = None
+
+    # Editor-specific specifications
+    editor_specs = {
+        "claude": {
+            "config_path": repo_path / ".mcp.json",
+            "config_key": "mcpServers",
+            "needs_dir": False,
+        },
+        "cursor": {
+            "config_path": repo_path / ".cursor" / "mcp.json",
+            "config_key": "mcpServers",
+            "needs_dir": True,
+        },
+        "vs": {
+            "config_path": repo_path / ".vscode" / "settings.json",
+            "config_key": "mcp.servers",
+            "needs_dir": True,
+        },
+    }
+
+    if editor not in editor_specs:
+        raise ValueError(f"Unsupported editor: {editor}")
+
+    spec = editor_specs[editor]
+    config_path = spec["config_path"]
+
+    # Create parent directory if needed
+    if spec["needs_dir"]:
+        config_path.parent.mkdir(exist_ok=True)
+
+    # Load existing config
+    config = _load_existing_config(config_path)
+
+    # Ensure config section exists
+    if spec["config_key"] not in config:
+        config[spec["config_key"]] = {}
+
+    # Build and add server configuration
+    server_config = _build_server_config(command, args, cwd, repo_path, storage_dir)
+    config[spec["config_key"]]["cicada"] = server_config
+
+    return config_path, config
+
+
+def create_config_yaml(repo_path: Path, storage_dir: Path) -> None:
+    """
+    Create config.yaml in storage directory.
+
+    Args:
+        repo_path: Path to the repository
+        storage_dir: Path to the storage directory
+    """
+    config_path = get_config_path(repo_path)
+    index_path = get_index_path(repo_path)
+
+    config_content = f"""repository:
+  path: {repo_path}
+
+storage:
+  index_path: {index_path}
+"""
+
+    with open(config_path, "w") as f:
+        f.write(config_content)
+
+    print(f"✓ Config file created at {config_path}")
+
+
+def index_repository(repo_path: Path) -> None:
+    """
+    Index the repository with keyword extraction enabled.
+
+    Args:
+        repo_path: Path to the repository
+
+    Raises:
+        Exception: If indexing fails
+    """
+    try:
+        index_path = get_index_path(repo_path)
+        indexer = ElixirIndexer(verbose=True)
+
+        # Index with keyword extraction enabled by default
+        # Note: Using 'small' model for compatibility with uvx
+        # For better accuracy, install permanently and use cicada-index with --spacy-model medium/large
+        indexer.index_repository(
+            repo_path=str(repo_path),
+            output_path=str(index_path),
+            extract_keywords=True,
+            spacy_model="small",
+        )
+
+        print(f"✓ Repository indexed at {index_path}")
+    except Exception as e:
+        print(f"Error: Failed to index repository: {e}")
+        print("Please check that the repository contains valid Elixir files.")
+        raise
+
+
+def setup(editor: EditorType, repo_path: Path | None = None) -> None:
+    """
+    Run the complete setup for the specified editor.
+
+    Args:
+        editor: Editor type (claude, cursor, vs)
+        repo_path: Path to the repository (defaults to current directory)
+    """
+    # Determine repository path
+    if repo_path is None:
+        repo_path = Path.cwd()
+    repo_path = repo_path.resolve()
+
+    print("=" * 60)
+    print(f"Cicada Setup for {editor.upper()}")
+    print("=" * 60)
+    print()
+
+    # Create storage directory
+    print(f"Repository: {repo_path}")
+    storage_dir = create_storage_dir(repo_path)
+    print(f"Storage: {storage_dir}")
+    print()
+
+    # Index repository
+    index_repository(repo_path)
+    print()
+
+    # Create config.yaml
+    create_config_yaml(repo_path, storage_dir)
+    print()
+
+    # Create MCP config for the editor
+    config_path, config_content = get_mcp_config_for_editor(
+        editor, repo_path, storage_dir
+    )
+
+    # Write config file
+    with open(config_path, "w") as f:
+        json.dump(config_content, f, indent=2)
+
+    print(f"✓ MCP configuration created at {config_path}")
+    print()
+
+    print("=" * 60)
+    print("✓ Setup Complete!")
+    print("=" * 60)
+    print()
+    print("Next steps:")
+    print(f"1. Restart {editor.upper()}")
+    print("2. Cicada MCP server will be available automatically")
+    print()
+    print("Storage location:")
+    print(f"  {storage_dir}")
+    print()
+    print("All index files are stored outside your repository.")
+    print(f"Only {config_path.name} was added to your repo.")
+    print()
+
+    # Check if running via uvx and suggest permanent installation
+    import shutil
+    from cicada import __version__
+
+    if not shutil.which("cicada-server"):
+        print("💡 Tip: For best experience, install Cicada permanently:")
+        print(
+            f"   uv tool install git+https://github.com/wende/cicada.git@v{__version__}"
+        )
+        print()
+        print("   Benefits:")
+        print("   • Faster MCP server startup")
+        print("   • Access to cicada-index with medium/large spaCy models")
+        print("   • PR indexing with cicada-index-pr")
+        print()
+
+
+def main():
+    """Main entry point for the simplified setup script."""
+    parser = argparse.ArgumentParser(
+        description="Cicada One-Command Setup",
+        epilog="Example: uvx cicada claude",
+    )
+    parser.add_argument(
+        "editor",
+        choices=["claude", "cursor", "vs"],
+        help="Editor to configure (claude=Claude Code, cursor=Cursor, vs=VS Code)",
+    )
+    parser.add_argument(
+        "repo",
+        nargs="?",
+        default=None,
+        help="Path to the Elixir repository (default: current directory)",
+    )
+
+    args = parser.parse_args()
+
+    # Determine repo path
+    repo_path = Path(args.repo) if args.repo else Path.cwd()
+
+    # Validate path exists
+    if not repo_path.exists():
+        print(f"Error: Path does not exist: {repo_path}")
+        sys.exit(1)
+
+    # Validate path is a directory
+    if not repo_path.is_dir():
+        print(f"Error: Path is not a directory: {repo_path}")
+        sys.exit(1)
+
+    # Check if it's an Elixir repository
+    if not (repo_path / "mix.exs").exists():
+        print(f"Error: {repo_path} does not appear to be an Elixir project")
+        print("(mix.exs not found)")
+        sys.exit(1)
+
+    # Run setup
+    try:
+        setup(args.editor, repo_path)
+    except Exception as e:
+        print(f"\nError: Setup failed: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

cicada/utils/__init__.py

@@ -0,0 +1,52 @@
+"""
+Utility modules for CICADA.
+
+This package contains shared utilities used across the codebase to reduce
+code duplication and improve maintainability.
+"""
+
+from .subprocess_runner import SubprocessRunner, run_git_command, run_gh_command
+from .path_utils import normalize_file_path, resolve_to_repo_root
+from .index_utils import (
+    load_index,
+    save_index,
+    merge_indexes_incremental,
+    validate_index_structure,
+)
+from .function_grouper import FunctionGrouper
+from .call_site_formatter import CallSiteFormatter
+from .signature_builder import SignatureBuilder
+from .text_utils import split_identifier, split_camel_snake_case
+from .storage import (
+    get_repo_hash,
+    get_storage_dir,
+    create_storage_dir,
+    get_index_path,
+    get_config_path,
+    get_hashes_path,
+    get_pr_index_path,
+)
+
+__all__ = [
+    "SubprocessRunner",
+    "run_git_command",
+    "run_gh_command",
+    "normalize_file_path",
+    "resolve_to_repo_root",
+    "load_index",
+    "save_index",
+    "merge_indexes_incremental",
+    "validate_index_structure",
+    "FunctionGrouper",
+    "CallSiteFormatter",
+    "SignatureBuilder",
+    "split_identifier",
+    "split_camel_snake_case",
+    "get_repo_hash",
+    "get_storage_dir",
+    "create_storage_dir",
+    "get_index_path",
+    "get_config_path",
+    "get_hashes_path",
+    "get_pr_index_path",
+]