codegraphcontext 0.4.16__tar.gz → 0.4.17__tar.gz

{codegraphcontext-0.4.16/src/codegraphcontext.egg-info → codegraphcontext-0.4.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraphcontext
-Version: 0.4.16
+Version: 0.4.17
 Summary: An MCP server that indexes local code into a graph database to provide context to AI assistants.
 Author-email: Shashank Shekhar Singh <shashankshekharsingh1205@gmail.com>
 License: MIT License
@@ -156,6 +156,8 @@ A powerful **MCP server** and **CLI toolkit** that indexes local code into a gra
 
 ## 📍 Quick Navigation
 * [🚀 Quick Start](#-installation--quick-start) 
+* [📋 Prerequisites](#-prerequisites)
+* [🏃 How to Run the Project Locally](#-how-to-run-the-project-locally)
 * [🌐 Supported Programming Languages](#supported-programming-languages) 
 * [🛠️ CLI Toolkit](#for-cli-toolkit-mode) 
 * [🤖 MCP Server](#-for-mcp-server-mode) 
@@ -183,7 +185,7 @@ A powerful **MCP server** and **CLI toolkit** that indexes local code into a gra
 ---
 
 ## Project Details
-- **Version:** 0.4.16
+- **Version:** 0.4.17
 - **Authors:** Shashank Shekhar Singh <shashankshekharsingh1205@gmail.com>
 - **License:** MIT License (See [LICENSE](LICENSE) for details)
 - **Website:** [CodeGraphContext](http://codegraphcontext.vercel.app/)
@@ -326,6 +328,84 @@ _If you’re using CodeGraphContext in your project, feel free to open a PR and
 
 ---
 
+## 📋 Prerequisites
+
+Before installing CodeGraphContext, ensure you have:
+
+* Python 3.10 or later
+* pip package manager
+* Git (optional, for cloning repositories)
+
+Verify your Python installation:
+
+```bash
+python --version
+```
+
+---
+
+## 🚀 Step-by-Step Setup Guide
+
+### Step 1: Install CodeGraphContext
+
+```bash
+pip install codegraphcontext
+```
+
+This command installs CodeGraphContext and all required dependencies.
+
+### Step 2: Verify Installation
+
+```bash
+codegraphcontext --help
+```
+
+If the command displays the available CLI commands, the installation was successful.
+
+### Step 3: Database Setup
+
+CodeGraphContext automatically uses an embedded database by default, so no additional configuration is required for most users.
+
+---
+
+## 🏃 How to Run the Project Locally
+
+### Index a Repository
+
+```bash
+codegraphcontext index .
+```
+
+This scans the current project and creates a searchable code graph.
+
+### View Indexed Repositories
+
+```bash
+codegraphcontext list
+```
+
+Displays all repositories currently indexed by CodeGraphContext.
+
+### Analyze Code
+
+```bash
+codegraphcontext analyze dead-code
+```
+
+Finds potentially unused code in the indexed repository.
+
+---
+
+## ✅ Verify Everything Works
+
+After indexing a repository, run:
+
+```bash
+codegraphcontext list
+```
+
+If the command executes successfully and displays indexed repositories, your setup is complete and CodeGraphContext is ready to use.
+
 ### For CLI Toolkit Mode
 
 **Start using immediately with CLI commands:**

{codegraphcontext-0.4.16 → codegraphcontext-0.4.17}/README.md

@@ -71,6 +71,8 @@ A powerful **MCP server** and **CLI toolkit** that indexes local code into a gra
 
 ## 📍 Quick Navigation
 * [🚀 Quick Start](#-installation--quick-start) 
+* [📋 Prerequisites](#-prerequisites)
+* [🏃 How to Run the Project Locally](#-how-to-run-the-project-locally)
 * [🌐 Supported Programming Languages](#supported-programming-languages) 
 * [🛠️ CLI Toolkit](#for-cli-toolkit-mode) 
 * [🤖 MCP Server](#-for-mcp-server-mode) 
@@ -98,7 +100,7 @@ A powerful **MCP server** and **CLI toolkit** that indexes local code into a gra
 ---
 
 ## Project Details
-- **Version:** 0.4.16
+- **Version:** 0.4.17
 - **Authors:** Shashank Shekhar Singh <shashankshekharsingh1205@gmail.com>
 - **License:** MIT License (See [LICENSE](LICENSE) for details)
 - **Website:** [CodeGraphContext](http://codegraphcontext.vercel.app/)
@@ -241,6 +243,84 @@ _If you’re using CodeGraphContext in your project, feel free to open a PR and
 
 ---
 
+## 📋 Prerequisites
+
+Before installing CodeGraphContext, ensure you have:
+
+* Python 3.10 or later
+* pip package manager
+* Git (optional, for cloning repositories)
+
+Verify your Python installation:
+
+```bash
+python --version
+```
+
+---
+
+## 🚀 Step-by-Step Setup Guide
+
+### Step 1: Install CodeGraphContext
+
+```bash
+pip install codegraphcontext
+```
+
+This command installs CodeGraphContext and all required dependencies.
+
+### Step 2: Verify Installation
+
+```bash
+codegraphcontext --help
+```
+
+If the command displays the available CLI commands, the installation was successful.
+
+### Step 3: Database Setup
+
+CodeGraphContext automatically uses an embedded database by default, so no additional configuration is required for most users.
+
+---
+
+## 🏃 How to Run the Project Locally
+
+### Index a Repository
+
+```bash
+codegraphcontext index .
+```
+
+This scans the current project and creates a searchable code graph.
+
+### View Indexed Repositories
+
+```bash
+codegraphcontext list
+```
+
+Displays all repositories currently indexed by CodeGraphContext.
+
+### Analyze Code
+
+```bash
+codegraphcontext analyze dead-code
+```
+
+Finds potentially unused code in the indexed repository.
+
+---
+
+## ✅ Verify Everything Works
+
+After indexing a repository, run:
+
+```bash
+codegraphcontext list
+```
+
+If the command executes successfully and displays indexed repositories, your setup is complete and CodeGraphContext is ready to use.
+
 ### For CLI Toolkit Mode
 
 **Start using immediately with CLI commands:**

{codegraphcontext-0.4.16 → codegraphcontext-0.4.17}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codegraphcontext"
-version = "0.4.16"
+version = "0.4.17"
 description = "An MCP server that indexes local code into a graph database to provide context to AI assistants."
 authors = [{ name = "Shashank Shekhar Singh", email = "shashankshekharsingh1205@gmail.com" }]
 readme = "README.md"

{codegraphcontext-0.4.16 → codegraphcontext-0.4.17}/src/codegraphcontext/api/router.py

@@ -13,6 +13,8 @@ from .schemas import (
 )
 from codegraphcontext.server import MCPServer
 
+import socket
+
 router = APIRouter()
 
 # Global server instance (initialized on startup)
@@ -25,9 +27,19 @@ def get_server() -> MCPServer:
         _server_instance = MCPServer(cwd=Path.cwd())
     return _server_instance
 
+def raise_service_unavailable(exc: Exception):
+    raise HTTPException(
+        status_code=503,
+        detail="Database service unavailable",
+    ) from exc
+
 @router.get("/status", response_model=ApiResponse)
 async def get_status(server: MCPServer = Depends(get_server)):
-    status = server.db_manager.is_connected()
+    try:
+        status = server.db_manager.is_connected()
+    except (OSError, socket.error) as exc:
+        raise_service_unavailable(exc)
+
     return ApiResponse(
         status="ok",
         message="Connected" if status else "Disconnected",
@@ -43,16 +55,35 @@ async def list_tools(server: MCPServer = Depends(get_server)):
 
 @router.post("/tools/call", response_model=ApiResponse)
 async def call_tool(
-    request: ToolCallRequest, 
+    request: ToolCallRequest,
     server: MCPServer = Depends(get_server)
 ):
     try:
-        result = await server.handle_tool_call(request.name, request.arguments)
+        result = await server.handle_tool_call(
+            request.name,
+            request.arguments
+        )
+
         if "error" in result:
-            return ApiResponse(status="error", error=result["error"])
-        return ApiResponse(status="ok", data=result)
+            return ApiResponse(
+                status="error",
+                error=result["error"]
+            )
+
+        return ApiResponse(
+            status="ok",
+            data=result
+        )
+
+    except (OSError, socket.error) as exc:
+        raise_service_unavailable(exc)
+
     except Exception as e:
-        return ApiResponse(status="error", error=str(e))
+        return ApiResponse(
+            status="error",
+            error=str(e)
+        )
+    
 
 @router.post("/index", response_model=ApiResponse)
 async def index_repository(
@@ -60,21 +91,27 @@ async def index_repository(
     background_tasks: BackgroundTasks,
     server: MCPServer = Depends(get_server)
 ):
-    # Map to add_code_to_graph tool
     args = {
         "path": request.path,
         "repo_name": request.repo_name,
         "branch": request.branch,
         "force": request.force
     }
-    
-    # We call handle_tool_call which is async
-    # But add_code_to_graph starts a background job anyway
-    result = await server.handle_tool_call("add_code_to_graph", args)
-    
+
+    try:
+        result = await server.handle_tool_call(
+            "add_code_to_graph",
+            args
+        )
+    except (OSError, socket.error) as exc:
+        raise_service_unavailable(exc)
+
     if "error" in result:
-        raise HTTPException(status_code=400, detail=result["error"])
-        
+        raise HTTPException(
+            status_code=400,
+            detail=result["error"]
+        )
+
     return ApiResponse(
         status="ok",
         message="Indexing job started",
@@ -86,17 +123,35 @@ async def execute_query(
     request: QueryRequest,
     server: MCPServer = Depends(get_server)
 ):
-    result = await server.handle_tool_call("execute_cypher_query", {
-        "cypher_query": request.query,
-        "params": request.params
-    })
-    
+    try:
+        result = await server.handle_tool_call(
+            "execute_cypher_query",
+            {
+                "cypher_query": request.query,
+                "params": request.params,
+            },
+        )
+    except (OSError, socket.error) as exc:
+        raise_service_unavailable(exc)
+
     if "error" in result:
         return ApiResponse(status="error", error=result["error"])
-        
+
     return ApiResponse(status="ok", data=result)
 
 @router.get("/repositories", response_model=ApiResponse)
-async def list_repositories(server: MCPServer = Depends(get_server)):
-    result = await server.handle_tool_call("list_indexed_repositories", {})
-    return ApiResponse(status="ok", data=result)
+async def list_repositories(
+    server: MCPServer = Depends(get_server)
+):
+    try:
+        result = await server.handle_tool_call(
+            "list_indexed_repositories",
+            {}
+        )
+    except (OSError, socket.error) as exc:
+        raise_service_unavailable(exc)
+
+    return ApiResponse(
+        status="ok",
+        data=result
+    )

{codegraphcontext-0.4.16 → codegraphcontext-0.4.17}/src/codegraphcontext/cli/cli_helpers.py

@@ -29,7 +29,13 @@ from ..tools.package_resolver import get_local_package_path
 from ..utils.debug_log import info_logger, warning_logger
 from ..core.database import Neo4jConnectionError
 from ..utils.repo_path import any_repo_matches_path
-from .config_manager import resolve_context, ResolvedContext, register_repo_in_context, ensure_first_run_bootstrap
+from .config_manager import (
+    resolve_context,
+    ResolvedContext,
+    register_repo_in_context,
+    ensure_first_run_bootstrap,
+    ContextNotFoundError,
+)
 
 console = Console()
 
@@ -41,6 +47,9 @@ def _fail_services_init() -> None:
 
 def _kuzu_fallback_path(ctx: ResolvedContext) -> Optional[str]:
     """Derive a KùzuDB directory when falling back from another backend."""
+    runtime = os.getenv("CGC_RUNTIME_DB_PATH")
+    if runtime:
+        return str(Path(runtime).expanduser().resolve())
     if ctx.db_path:
         return str(Path(ctx.db_path).parent / "kuzudb")
     try:
@@ -85,7 +94,11 @@ def _initialize_services(
     """
     ensure_first_run_bootstrap()
     console.print("[dim]Resolving context...[/dim]")
-    ctx = resolve_context(cli_context_flag, cwd=cwd)
+    try:
+        ctx = resolve_context(cli_context_flag, cwd=cwd)
+    except ContextNotFoundError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(code=1)
     
     # Let the user know what context we're operating in
     if ctx.mode == "named":
@@ -120,6 +133,8 @@ def _initialize_services(
         # Check if this is a FalkorDB failure that should trigger a KùzuDB fallback
         from ..core.database_falkordb import FalkorDBUnavailableError
         if isinstance(e, FalkorDBUnavailableError):
+            from ..core import mark_falkordb_unavailable
+            mark_falkordb_unavailable()
             console.print(f"[yellow]⚠ FalkorDB Lite is not functional in this environment: {e}[/yellow]")
             console.print("[cyan]Falling back to KùzuDB for a reliable experience...[/cyan]")
             
@@ -219,8 +234,8 @@ async def _run_index_with_progress(graph_builder: GraphBuilder, path_obj: Path,
                 if job.total_files > 0:
                     progress.update(task_id, total=job.total_files, completed=job.processed_files)
                 
-                # Update the current filename in the UI
-                current_file = job.current_file or ""
+                # Prefer post-processing status over the last parsed file path
+                current_file = job.status_message or job.current_file or ""
                 if len(current_file) > 40:
                     current_file = "..." + current_file[-37:]
                 progress.update(task_id, filename=current_file)
@@ -283,9 +298,10 @@ def index_helper(path: str, context: Optional[str] = None):
         except Exception as e:
             console.print(f"[yellow]Warning: Could not check file count: {e}. Proceeding with indexing...[/yellow]")
 
-    # Auto-register the repo into the named context (auto-creates if needed)
     if context and ctx.mode == "named":
-        register_repo_in_context(context, str(path_obj), auto_create=True)
+        if not register_repo_in_context(context, str(path_obj), auto_create=False):
+            db_manager.close_driver()
+            raise typer.Exit(code=1)
 
     console.print(f"Starting indexing for: {path_obj}")
 
@@ -327,7 +343,7 @@ def add_package_helper(package_name: str, language: str, context: Optional[str]
     if not package_path_str:
         console.print(f"[red]Error: Could not find package '{package_name}' for language '{language}'.[/red]")
         db_manager.close_driver()
-        return
+        raise typer.Exit(code=1)
 
     package_path = Path(package_path_str)
     
@@ -345,6 +361,7 @@ def add_package_helper(package_name: str, language: str, context: Optional[str]
         console.print(f"[green]Successfully finished indexing package: {package_name}[/green]")
     except Exception as e:
         console.print(f"[bold red]An error occurred during package indexing:[/bold red] {e}")
+        raise typer.Exit(code=1)
     finally:
         db_manager.close_driver()
 
@@ -406,23 +423,26 @@ def cypher_helper(query: str, context: Optional[str] = None):
         _fail_services_init()
 
     db_manager, _, _, ctx = services
-    
-    # Replicating safety checks from MCPServer (using word boundaries to avoid false positives like 'createEmail')
-    import re
-    forbidden_keywords = ['CREATE', 'MERGE', 'DELETE', 'SET', 'REMOVE', 'DROP', 'CALL apoc']
-    pattern = r'\b(' + '|'.join(forbidden_keywords) + r')\b'
-    if re.search(pattern, query, re.IGNORECASE):
-        console.print("[bold red]Error: This command only supports read-only queries.[/bold red]")
+
+    from ..utils.cypher_readonly import is_read_only_cypher, read_only_rejection_message
+
+    if not is_read_only_cypher(query):
+        console.print(f"[bold red]Error:[/bold red] {read_only_rejection_message()}")
         db_manager.close_driver()
         raise typer.Exit(code=1)
 
+    backend = getattr(db_manager, "get_backend_type", lambda: "neo4j")()
+    session_kwargs = {"default_access_mode": "READ"} if backend == "neo4j" else {}
+
     try:
-        with db_manager.get_driver().session() as session:
+        with db_manager.get_driver().session(**session_kwargs) as session:
             result = session.run(query)
             records = [record.data() for record in result]
             console.print(json.dumps(records, indent=2))
     except Exception as e:
         console.print(f"[bold red]An error occurred while executing query:[/bold red] {e}")
+        db_manager.close_driver()
+        raise typer.Exit(code=1)
     finally:
         db_manager.close_driver()
 
@@ -430,34 +450,25 @@ def cypher_helper(query: str, context: Optional[str] = None):
 def cypher_helper_visual(query: str, context: Optional[str] = None):
     """Executes a read-only Cypher query and visualizes the results."""
     from .visualizer import visualize_cypher_results
-    
+    from ..utils.cypher_readonly import is_read_only_cypher, read_only_rejection_message
+
     services = _initialize_services(context)
     if not all(services[:3]):
         _fail_services_init()
 
     db_manager, _, _, ctx = services
-    
-    # Replicating safety checks from MCPServer (using word boundaries to avoid false positives like 'createEmail')
-    import re
-    forbidden_keywords = ['CREATE', 'MERGE', 'DELETE', 'SET', 'REMOVE', 'DROP', 'CALL apoc']
-    pattern = r'\b(' + '|'.join(forbidden_keywords) + r')\b'
-    if re.search(pattern, query, re.IGNORECASE):
-        console.print("[bold red]Error: This command only supports read-only queries.[/bold red]")
+
+    if not is_read_only_cypher(query):
+        console.print(f"[bold red]Error:[/bold red] {read_only_rejection_message()}")
         db_manager.close_driver()
         raise typer.Exit(code=1)
 
     try:
-        with db_manager.get_driver().session() as session:
-            result = session.run(query)
-            records = [record.data() for record in result]
-            
-            if not records:
-                console.print("[yellow]No results to visualize.[/yellow]")
-                return  # finally block will close driver
-            
-            visualize_cypher_results(records, query)
+        visualize_cypher_results(query)
     except Exception as e:
         console.print(f"[bold red]An error occurred while executing query:[/bold red] {e}")
+        db_manager.close_driver()
+        raise typer.Exit(code=1)
     finally:
         db_manager.close_driver()
 
@@ -466,7 +477,12 @@ import uvicorn
 import urllib.parse
 from ..viz.server import run_server, set_db_manager
 
-def visualize_helper(repo_path: Optional[str] = None, port: int = 8000, context: Optional[str] = None):
+def visualize_helper(
+    repo_path: Optional[str] = None,
+    port: int = 8000,
+    context: Optional[str] = None,
+    cypher_query: Optional[str] = None,
+):
     """Generates an interactive visualization using the Playground UI."""
     services = _initialize_services(context)
     if not all(services[:3]):
@@ -537,7 +553,9 @@ def visualize_helper(repo_path: Optional[str] = None, port: int = 8000, context:
     params = {"backend": backend_url}
     if repo_path:
         params["repo_path"] = str(Path(repo_path).resolve())
-    
+    if cypher_query:
+        params["cypher_query"] = cypher_query
+
     query_string = urllib.parse.urlencode(params)
     visualization_url = f"{backend_url}/explore?{query_string}"
     
@@ -558,6 +576,7 @@ def visualize_helper(repo_path: Optional[str] = None, port: int = 8000, context:
         run_server(host="127.0.0.1", port=port, static_dir=str(static_dir))
     except Exception as e:
         console.print(f"[bold red]An error occurred while running the server:[/bold red] {e}")
+        raise typer.Exit(code=1)
     finally:
         db_manager.close_driver()
 
@@ -565,17 +584,18 @@ def visualize_helper(repo_path: Optional[str] = None, port: int = 8000, context:
 def reindex_helper(path: str, context: Optional[str] = None):
     """Force re-index by deleting and rebuilding the repository."""
     time_start = time.time()
-    services = _initialize_services(context)
+    path_obj = Path(path).resolve()
+    index_cwd = path_obj if path_obj.is_dir() else path_obj.parent
+    services = _initialize_services(context, cwd=index_cwd)
     if not all(services[:3]):
         _fail_services_init()
 
     db_manager, graph_builder, code_finder, ctx = services
-    path_obj = Path(path).resolve()
 
     if not path_obj.exists():
         console.print(f"[red]Error: Path does not exist: {path_obj}[/red]")
         db_manager.close_driver()
-        return
+        raise typer.Exit(code=1)
 
     # Check if already indexed
     indexed_repos = code_finder.list_indexed_repositories()
@@ -589,7 +609,7 @@ def reindex_helper(path: str, context: Optional[str] = None):
         except Exception as e:
             console.print(f"[red]Error deleting old index: {e}[/red]")
             db_manager.close_driver()
-            return
+            raise typer.Exit(code=1)
     
     console.print(f"[cyan]Re-indexing: {path_obj}[/cyan]")
     
@@ -627,14 +647,13 @@ def clean_helper(context: Optional[str] = None):
         batch_size = 500
         
         with db_manager.get_driver().session() as session:
-            # Layer-by-layer deletion: iteratively delete nodes that lost
-            # their CONTAINS parent. Each pass peels one layer of the
-            # Repository → File → Class/Function → Variable hierarchy.
+            # Delete nodes with no incoming relationships (true orphans).
+            # Parameters (HAS_PARAMETER), import Modules (IMPORTS), etc. are kept.
             while True:
                 result = session.run("""
                     MATCH (n)
                     WHERE NOT n:Repository
-                      AND NOT ()-[:CONTAINS]->(n)
+                      AND NOT ()-[]->(n)
                     WITH n LIMIT $batch_size
                     DETACH DELETE n
                     RETURN count(n) as deleted
@@ -762,7 +781,7 @@ def stats_helper(path: str = None, context: Optional[str] = None):
         db_manager.close_driver()
 
 
-def watch_helper(path: str, context: Optional[str] = None):
+def watch_helper(path: str, context: Optional[str] = None, use_polling: Optional[bool] = None):
     """Watch a directory for changes and auto-update the graph (blocking mode)."""
     import logging
     from ..core.watcher import CodeWatcher
@@ -782,12 +801,12 @@ def watch_helper(path: str, context: Optional[str] = None):
     if not path_obj.exists():
         console.print(f"[red]Error: Path does not exist: {path_obj}[/red]")
         db_manager.close_driver()
-        return
+        raise typer.Exit(code=1)
     
     if not path_obj.is_dir():
         console.print(f"[red]Error: Path must be a directory: {path_obj}[/red]")
         db_manager.close_driver()
-        return
+        raise typer.Exit(code=1)
 
     console.print(f"[bold cyan]🔍 Watching {path_obj} for changes...[/bold cyan]")
     
@@ -817,7 +836,7 @@ def watch_helper(path: str, context: Optional[str] = None):
     
     # Create watcher instance
     job_manager = JobManager()
-    watcher = CodeWatcher(graph_builder, job_manager)
+    watcher = CodeWatcher(graph_builder, job_manager, use_polling=use_polling)
     
     try:
         # Start the observer thread