sql-code-graph 0.2.1__py3-none-any.whl

sqlcg/cli/commands/git.py

@@ -0,0 +1,73 @@
+"""Git integration commands for sqlcg."""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+app = typer.Typer(name="git", help="Git integration commands")
+
+
+@app.command("install-hooks")
+def install_hooks(
+    repo: Path | None = typer.Option(  # noqa: B008
+        None, "--repo", "-r", help="Path to git repository (default: current directory)"
+    ),
+) -> None:
+    """Install git hooks for sqlcg integration.
+
+    Writes a post-checkout hook that triggers graph resync after branch switches.
+    Idempotent: running multiple times produces one hook entry.
+    """
+    if repo is None:
+        repo = Path.cwd()
+
+    git_dir = repo / ".git"
+    hooks_dir = git_dir / "hooks"
+
+    if not git_dir.exists():
+        console.print("[red]Error: not a git repository[/red]")
+        raise typer.Exit(1)
+
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+
+    hook_path = hooks_dir / "post-checkout"
+    hook_sentinel = "# sqlcg post-checkout hook"
+
+    # Hook script content
+    hook_script = """#!/bin/sh
+# sqlcg post-checkout hook — resync graph after branch switch
+# $3 == 1 means branch checkout (not file checkout); skip file checkouts
+[ "$3" = "1" ] || exit 0
+sqlcg index "$(git rev-parse --show-toplevel)" --dialect auto --quiet || true
+"""
+
+    # Check if hook already exists
+    if hook_path.exists():
+        existing_content = hook_path.read_text()
+        if hook_sentinel in existing_content:
+            # Already installed, idempotent: skip silently
+            return
+        else:
+            # Existing hook without sqlcg sentinel
+            console.print(
+                "[yellow]Warning: existing post-checkout hook found that was not created "
+                "by sqlcg.[/yellow]"
+            )
+            console.print(
+                "[yellow]To integrate sqlcg, manually append the following to "
+                ".git/hooks/post-checkout:[/yellow]"
+            )
+            console.print("")
+            console.print("[cyan]" + hook_script.rstrip() + "[/cyan]")
+            return
+
+    # Write hook script
+    hook_path.write_text(hook_script)
+
+    # Make it executable
+    hook_path.chmod(0o755)
+
+    console.print("[green]Installed git hook:[/green] .git/hooks/post-checkout")

sqlcg/cli/commands/index.py

@@ -0,0 +1,92 @@
+"""Index command for scanning and indexing SQL files."""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from sqlcg.core.config import get_backend, get_db_path, get_dialect
+from sqlcg.indexer.indexer import Indexer
+
+console = Console()
+
+
+def index_cmd(  # noqa: B008
+    path: Path = typer.Argument(..., help="Directory to index"),  # noqa: B008
+    dialect: str | None = typer.Option(  # noqa: B008
+        None, "--dialect", "-d", help="SQL dialect (or 'auto' to read from .sqlcg.toml)"
+    ),
+    dbt_manifest: Path | None = typer.Option(  # noqa: B008
+        None, "--dbt-manifest", help="Path to dbt manifest"
+    ),
+    timeout_per_file: int = typer.Option(  # noqa: B008
+        30, "--timeout-per-file", help="Timeout per file in seconds"
+    ),
+    no_ddl: bool = typer.Option(  # noqa: B008
+        False, "--no-ddl", help="Skip DDL statements (not yet fully implemented)"
+    ),
+    schema_from_info_schema: str | None = typer.Option(  # noqa: B008
+        None, "--schema-from-info-schema", hidden=True, help="(Not yet implemented)"
+    ),
+    quiet: bool = typer.Option(  # noqa: B008
+        False, "--quiet", "-q", help="Suppress summary console output"
+    ),
+) -> None:
+    """Index SQL files in a directory."""
+    if schema_from_info_schema:
+        console.print("[red]--schema-from-info-schema is not yet implemented (v2)[/red]")
+        raise typer.Exit(1)
+
+    # TODO: wire no_ddl through to the indexer once it supports the parameter
+    if no_ddl:
+        console.print("[yellow]Note: --no-ddl is not yet fully implemented[/yellow]")
+
+    # Resolve dialect: 'auto' reads from .sqlcg.toml, otherwise use provided value
+    if dialect == "auto":
+        dialect = get_dialect(path)
+
+    db_path = get_db_path()
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with get_backend() as backend:
+        backend.init_schema()
+
+        # Create Repo node for this repository
+        from sqlcg.core.schema import NodeLabel
+
+        abs_path = str(path.resolve())
+        backend.upsert_node(
+            NodeLabel.REPO,
+            abs_path,
+            {
+                "path": abs_path,
+                "name": path.name,
+            },
+        )
+
+        # Index the repository
+        indexer = Indexer()
+        summary = indexer.index_repo(path, dialect, backend, dbt_manifest, timeout_per_file)
+
+        # Connect files to repo
+        from sqlcg.core.schema import RelType
+
+        files_query = "MATCH (f:File) WHERE f.path STARTS WITH $repo_prefix RETURN f.path AS path"
+        file_rows = backend.run_read(files_query, {"repo_prefix": abs_path})
+        for row in file_rows:
+            backend.upsert_edge(
+                NodeLabel.FILE,
+                row["path"],
+                NodeLabel.REPO,
+                abs_path,
+                RelType.BELONGS_TO,
+                {},
+            )
+
+        # Print summary unless --quiet is specified
+        if not quiet:
+            console.print(
+                f"[green]Indexed[/green] {summary['files_parsed']} files — "
+                f"{summary['tables_found']} tables, {summary['lineage_edges_created']} edges, "
+                f"{summary['parse_errors']} errors"
+            )

sqlcg/cli/commands/install.py

@@ -0,0 +1,60 @@
+"""Install sqlcg as an MCP server in Claude Code."""
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+_SETTINGS_PATH = Path.home() / ".claude" / "settings.json"
+_SERVER_KEY = "sql-code-graph"
+
+
+def install_cmd(
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print config without writing"),
+) -> None:
+    """Register sqlcg as an MCP server in Claude Code (~/.claude/settings.json)."""
+    if shutil.which("uvx"):
+        entry: dict = {"command": "uvx", "args": ["sql-code-graph", "mcp", "start"]}
+    else:
+        entry = {"command": "sqlcg", "args": ["mcp", "start"]}
+
+    settings_path = _SETTINGS_PATH
+    if settings_path.exists():
+        try:
+            settings: dict = json.loads(settings_path.read_text())
+        except json.JSONDecodeError:
+            console.print(
+                f"[yellow]Warning:[/yellow] {settings_path} contains invalid JSON — "
+                "mcpServers key will be added"
+            )
+            settings = {}
+    else:
+        settings = {}
+
+    mcp_servers: dict = settings.setdefault("mcpServers", {})
+
+    if mcp_servers.get(_SERVER_KEY) == entry:
+        console.print(f"[green]Already configured:[/green] {_SERVER_KEY} → {settings_path}")
+        return
+
+    mcp_servers[_SERVER_KEY] = entry
+
+    if dry_run:
+        console.print("[dim]--dry-run: would write:[/dim]")
+        console.print_json(json.dumps(settings, indent=2))
+        return
+
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = settings_path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(settings, indent=2) + "\n")
+    os.replace(tmp, settings_path)
+
+    cmd_str = f"{entry['command']} {' '.join(entry['args'])}"
+    console.print(f"[green]Configured:[/green] {_SERVER_KEY} → {cmd_str}")
+    console.print(f"[dim]Written to {settings_path}[/dim]")
+    console.print("\nRestart Claude Code to pick up the new MCP server.")

sqlcg/cli/commands/mcp.py

@@ -0,0 +1,54 @@
+"""MCP server commands."""
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(help="MCP server commands")
+console = Console()
+
+_SERVER_KEY = "sql-code-graph"
+
+
+def _server_entry() -> dict:
+    if shutil.which("uvx"):
+        return {"command": "uvx", "args": ["sql-code-graph", "mcp", "start"]}
+    return {"command": "sqlcg", "args": ["mcp", "start"]}
+
+
+@app.command("setup")
+def mcp_setup(print_only: bool = typer.Option(True, "--print/--write")) -> None:
+    """Print or write MCP server config JSON."""
+    entry = _server_entry()
+    if print_only:
+        console.print_json(json.dumps({"mcpServers": {_SERVER_KEY: entry}}, indent=2))
+        return
+
+    config_path = Path.home() / ".claude" / "settings.json"
+    if config_path.exists():
+        try:
+            settings: dict = json.loads(config_path.read_text())
+        except json.JSONDecodeError:
+            settings = {}
+    else:
+        settings = {}
+
+    settings.setdefault("mcpServers", {})[_SERVER_KEY] = entry
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = config_path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(settings, indent=2) + "\n")
+    os.replace(tmp, config_path)
+    console.print(f"[green]Configuration written to[/green] {config_path}")
+
+
+@app.command("start")
+def mcp_start() -> None:
+    """Start the MCP server."""
+    from sqlcg.server.server import main as server_main
+
+    server_main()

sqlcg/cli/commands/report.py

@@ -0,0 +1,135 @@
+"""The sqlcg report command — generate metrics and feedback reports."""
+
+import hashlib
+import urllib.parse
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from sqlcg.metrics.store import MetricsStore
+from sqlcg.utils.logging import getLogger
+
+logger = getLogger(__name__)
+console = Console()
+
+
+def report_cmd(
+    stdout: bool = typer.Option(False, "--stdout", help="Print to stdout instead of file"),  # noqa: B008
+    output: Path | None = typer.Option(  # noqa: B008
+        None,
+        "--output",
+        "-o",
+        help="Output file path",
+    ),
+) -> None:
+    """Generate a metrics report with FP clusters and parse error patterns.
+
+    Analyzes feedback and index run data to identify:
+    - False positive clusters (files/patterns with >50% FP rate, min 3 samples)
+    - Parse error clusters (repos with persistent parse errors)
+    - Provides a pre-filled GitHub issue URL for reporting problems
+
+    If no metrics database exists, prints a message and exits 0.
+    """
+    metrics_path = Path.home() / ".sqlcg" / "metrics.db"
+
+    if not metrics_path.exists():
+        message = "No metrics collected yet."
+        console.print(message)
+        return
+
+    try:
+        metrics = MetricsStore(metrics_path)
+        metrics.init_schema()
+
+        # Section 1: FP clusters
+        fp_clusters = metrics.execute_query(
+            """
+            SELECT query,
+                   SUM(CASE WHEN label = 'FP' THEN 1 ELSE 0 END) AS fp_count,
+                   COUNT(*) AS total,
+                   CAST(SUM(CASE WHEN label = 'FP' THEN 1 ELSE 0 END) AS REAL) / COUNT(*) AS fp_rate
+            FROM feedback
+            GROUP BY query
+            HAVING total >= 3 AND fp_rate > 0.5
+            ORDER BY fp_rate DESC
+            """
+        )
+
+        # Section 2: Parse error clusters
+        error_clusters = metrics.execute_query(
+            """
+            SELECT repo_path, COUNT(*) AS run_count,
+                   SUM(parse_errors) AS total_errors,
+                   CAST(SUM(parse_errors) AS REAL) / NULLIF(SUM(files_parsed), 0) AS error_rate
+            FROM index_runs
+            GROUP BY repo_path
+            HAVING run_count >= 2 AND total_errors > 0
+            ORDER BY total_errors DESC
+            """
+        )
+
+        # Build report content
+        report_lines = []
+
+        # Section 1: FP clusters
+        report_lines.append("## False Positive Clusters\n")
+        if fp_clusters:
+            report_lines.append("| Query | FP Count | Total | FP Rate |\n")
+            report_lines.append("|---|---|---|---|\n")
+            for row in fp_clusters:
+                query, fp_count, total, fp_rate = row
+                rate_pct = fp_rate * 100 if fp_rate else 0
+                report_lines.append(f"| {query} | {fp_count} | {total} | {rate_pct:.1f}% |\n")
+        else:
+            report_lines.append("No FP clusters found (need ≥3 samples per query pattern).\n")
+        report_lines.append("\n")
+
+        # Section 2: Parse error clusters
+        report_lines.append("## Parse Error Clusters\n")
+        if error_clusters:
+            report_lines.append("| Repo Path | Runs | Total Errors | Error Rate |\n")
+            report_lines.append("|---|---|---|---|\n")
+            for row in error_clusters:
+                repo_path, run_count, total_errors, error_rate = row
+                rate_pct = error_rate * 100 if error_rate else 0
+                report_lines.append(
+                    f"| {repo_path} | {run_count} | {total_errors} | {rate_pct:.1f}% |\n"
+                )
+        else:
+            report_lines.append("No parse error clusters found.\n")
+        report_lines.append("\n")
+
+        report_content = "".join(report_lines)
+
+        # Section 3: GitHub issue URL
+        report_hash = hashlib.md5(report_content.encode()).hexdigest()[:8]
+        issue_title = f"[sqlcg metrics] FP clusters report {report_hash}"
+        issue_body_truncated = report_content[:2000]
+        encoded_title = urllib.parse.quote(issue_title)
+        encoded_body = urllib.parse.quote(issue_body_truncated)
+        github_url = (
+            f"https://github.com/Warhorze/sql-code-graph/issues/new?"
+            f"title={encoded_title}&body={encoded_body}"
+        )
+
+        report_lines.append("## File an Issue\n")
+        report_lines.append(f"[Report metrics issues on GitHub]({github_url})\n")
+
+        final_report = "".join(report_lines)
+
+        # Output
+        if stdout:
+            console.print(final_report)
+        else:
+            output_path = output or Path("docs/METRICS_REPORT.md")
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(final_report)
+            console.print(f"Report written to {output_path}")
+
+        metrics.close()
+
+    except Exception as exc:
+        logger.error(f"Failed to generate report: {exc}")
+        console.print(f"[red]Error: {exc}[/red]")

sqlcg/cli/commands/watch.py

@@ -0,0 +1,57 @@
+"""Watch command for monitoring file changes."""
+
+import time
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from watchdog.observers import Observer
+
+from sqlcg.core.config import get_backend, get_db_path
+from sqlcg.core.jobs import WatchJobManager
+from sqlcg.indexer.indexer import Indexer
+from sqlcg.indexer.watcher import SqlFileEventHandler
+from sqlcg.utils.ignore import load_ignore_spec
+
+console = Console()
+
+
+def watch_cmd(  # noqa: B008
+    path: Path = typer.Argument(..., help="Directory to watch"),  # noqa: B008
+    dialect: str | None = typer.Option(  # noqa: B008
+        None, "--dialect", "-d", help="SQL dialect"
+    ),
+) -> None:
+    """Watch a directory and re-index on SQL file changes."""
+    db_path = get_db_path()
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with get_backend() as backend:
+        backend.init_schema()
+
+        indexer = Indexer()
+
+        # Initial full index
+        console.print(f"Indexing {path}...")
+        indexer.index_repo(path, dialect, backend)
+
+        spec = load_ignore_spec(path)
+        job_manager = WatchJobManager(indexer, backend, dialect)
+        handler = SqlFileEventHandler(job_manager, backend, spec, path, indexer=indexer)
+        observer = Observer()
+        observer.schedule(handler, str(path), recursive=True)
+        observer.start()
+        console.print(f"[green]Watching[/green] {path} — press Ctrl+C to stop")
+        try:
+            while observer.is_alive():
+                time.sleep(1)
+        except (KeyboardInterrupt, SystemExit):
+            pass
+        finally:
+            observer.stop()
+            observer.join(timeout=5)
+            job_manager.cancel_all()
+            if handler._branch_monitor is not None:
+                handler._branch_monitor.stop()
+                handler._branch_monitor.join(timeout=5)
+            console.print("Stopped.")

sqlcg/cli/main.py

@@ -0,0 +1,40 @@
+"""Main CLI entry point for sqlcg."""
+
+import typer
+from dotenv import load_dotenv
+
+from sqlcg.cli.commands import analyze, db, find, gain, git, index, install, mcp, report, watch
+
+app = typer.Typer(name="sqlcg", help="SQL code graph analyzer")
+
+# Register subcommand groups
+app.add_typer(db.app, name="db")
+app.add_typer(find.app, name="find")
+app.add_typer(analyze.app, name="analyze")
+app.add_typer(mcp.app, name="mcp")
+app.add_typer(git.app, name="git")
+
+# Register single commands
+app.command("index")(index.index_cmd)
+app.command("watch")(watch.watch_cmd)
+app.command("gain")(gain.gain_cmd)
+app.command("report")(report.report_cmd)
+app.command("install")(install.install_cmd)
+
+
+@app.command()
+def version() -> None:
+    """Show version."""
+    from sqlcg import __version__
+
+    typer.echo(f"sqlcg version {__version__}")
+
+
+def main() -> None:
+    """SQL Code Graph - SQL lineage and dependency analysis tool."""
+    load_dotenv()
+    app()
+
+
+if __name__ == "__main__":
+    main()

sqlcg/core/__init__.py

@@ -0,0 +1,8 @@
+"""Core database and schema modules."""
+
+from sqlcg.core import schema
+from sqlcg.core.graph_db import GraphBackend
+from sqlcg.core.kuzu_backend import KuzuBackend
+from sqlcg.core.neo4j_backend import Neo4jBackend
+
+__all__ = ["GraphBackend", "KuzuBackend", "Neo4jBackend", "schema"]

sqlcg/core/config.py

@@ -0,0 +1,104 @@
+"""Configuration management for sqlcg."""
+
+import os
+import tomllib
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from sqlcg.core.graph_db import GraphBackend
+
+
+class KuzuConfig(BaseModel):
+    """Configuration for KùzuDB backend."""
+
+    db_path: Path = Field(default_factory=lambda: Path.home() / ".sqlcg" / "graph.db")
+
+    @classmethod
+    def from_env(cls) -> "KuzuConfig":
+        """Load KùzuDB config from environment variables.
+
+        Returns:
+            KuzuConfig instance with environment-overridden values if present.
+        """
+        env_path = os.getenv("SQLCG_DB_PATH")
+        return cls(db_path=Path(env_path)) if env_path else cls()
+
+
+class Neo4jConfig(BaseModel):
+    """Configuration for Neo4j backend."""
+
+    uri: str = Field(default="bolt://localhost:7687")
+    user: str = Field(default="neo4j")
+    password: str = Field(default="password")
+
+    @classmethod
+    def from_env(cls) -> "Neo4jConfig":
+        """Load Neo4j config from environment variables.
+
+        Returns:
+            Neo4jConfig instance with environment-overridden values if present.
+        """
+        return cls(
+            uri=os.getenv("NEO4J_URI", "bolt://localhost:7687"),
+            user=os.getenv("NEO4J_USER", "neo4j"),
+            password=os.getenv("NEO4J_PASSWORD", "password"),
+        )
+
+
+def get_db_path() -> Path:
+    """Get the database path from environment or use default.
+
+    Returns:
+        Path to the KùzuDB database file
+    """
+    return KuzuConfig.from_env().db_path
+
+
+def get_dialect(path: Path) -> str:
+    """Get the SQL dialect from .sqlcg.toml or fall back to snowflake.
+
+    Args:
+        path: Root directory to search for .sqlcg.toml
+
+    Returns:
+        SQL dialect string (e.g., "snowflake", "bigquery", "postgres")
+    """
+    config_file = Path(path) / ".sqlcg.toml"
+    if config_file.exists():
+        try:
+            with open(config_file, "rb") as f:
+                config = tomllib.load(f)
+            dialect = config.get("sqlcg", {}).get("dialect")
+            if dialect:
+                return dialect
+        except Exception:
+            pass
+    return "snowflake"
+
+
+def get_backend() -> "GraphBackend":
+    """Get a graph backend instance respecting the SQLCG_BACKEND env var.
+
+    Returns:
+        A GraphBackend instance (KuzuBackend by default, or Neo4jBackend)
+
+    Raises:
+        ValueError: If backend type is not recognized
+    """
+    backend_type = os.getenv("SQLCG_BACKEND", "kuzu")
+
+    if backend_type == "kuzu":
+        from sqlcg.core.kuzu_backend import KuzuBackend
+
+        kuzu_cfg = KuzuConfig.from_env()
+        return KuzuBackend(str(kuzu_cfg.db_path))
+    elif backend_type == "neo4j":
+        from sqlcg.core.neo4j_backend import Neo4jBackend
+
+        neo4j_cfg = Neo4jConfig.from_env()
+        return Neo4jBackend(neo4j_cfg.uri, neo4j_cfg.user, neo4j_cfg.password)
+    else:
+        raise ValueError(f"Unknown backend type: {backend_type}")