sql-code-graph 0.3.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

sqlcg/cli/commands/uninstall.py

@@ -28,6 +28,8 @@ def uninstall_cmd(  # noqa: B008
     Step 1: Remove MCP registration from ~/.claude/settings.json
     Step 2: Optionally delete the KùzuDB graph database
     Step 3: Remove git hook sentinel block from .git/hooks/post-checkout
+    Step 4: Remove sqlcg skill directory from ~/.claude/skills/sqlcg/ and
+            <repo>/.claude/skills/sqlcg/
     """
     # Step 1: Remove MCP entry from settings.json
     _step1_remove_mcp_entry()
@@ -44,6 +46,9 @@ def uninstall_cmd(  # noqa: B008
     repo_path = repo if repo else Path.cwd()
     _step3_remove_git_hook(repo_path)
 
+    # Step 4: Remove sqlcg skill directory
+    _step4_remove_skill(repo_path)
+
 
 def _step1_remove_mcp_entry() -> None:
     """Remove the 'sql-code-graph' entry from ~/.claude/settings.json."""
@@ -130,84 +135,134 @@ def _step2_delete_database(force: bool) -> None:
                 console.print(f"[yellow]Warning:[/yellow] Failed to delete metrics store: {e}")
 
 
-def _step3_remove_git_hook(repo_path: Path) -> None:
-    """Remove the git hook sentinel block from .git/hooks/post-checkout."""
-    hook_file = repo_path / ".git" / "hooks" / "post-checkout"
+def _strip_sentinel_block(content: str, sentinel: str) -> str:
+    """Strip the block introduced by sentinel from hook file content.
 
-    if not hook_file.exists():
-        console.print(f"[yellow]No git hook found in {repo_path}[/yellow]")
-        return
+    The block starts at the sentinel line and extends until an empty line that is followed
+    by non-empty content (end-of-block), or until the end of file.
 
-    # Read the file
-    content = hook_file.read_text()
-
-    # Strip the sentinel block: from "# sqlcg post-checkout hook" to the end of the block
-    # The block ends when we encounter a line that doesn't start with whitespace/# or is empty
-    # followed by non-empty content
+    Returns the stripped content (may be empty if the sentinel was the only content).
+    """
     lines = content.split("\n")
     filtered_lines = []
     skip_mode = False
 
     for i, line in enumerate(lines):
-        if "# sqlcg post-checkout hook" in line:
+        if sentinel in line:
             skip_mode = True
             continue
 
         if skip_mode:
-            # Skip all lines that are part of the hook block
-            # The block extends from the sentinel comment until we hit an empty line
-            # followed by non-hook content, or until the end of file
             if line.strip() == "":
-                # Check if there's content after this blank line that's not the hook
                 remaining = "\n".join(lines[i + 1 :]).strip()
                 if remaining:
-                    # There's content after this blank line, so end the skip mode
                     skip_mode = False
-                    filtered_lines.append("")  # Preserve the blank line separator
-                # else: blank line is at end of file, just skip it
-            # else: continue skipping
+                    filtered_lines.append("")  # Preserve blank-line separator
+                # else: trailing blank line — skip
+            # else: continue skipping body lines
             continue
 
         filtered_lines.append(line)
 
-    # Reconstruct the content
     if filtered_lines:
-        new_content = "\n".join(filtered_lines).strip() + "\n"
-    else:
-        new_content = ""
+        return "\n".join(filtered_lines).strip() + "\n"
+    return ""
+
+
+def _remove_single_hook(repo_path: Path, filename: str, sentinel: str) -> None:
+    """Strip the sqlcg sentinel block from one git hook file.
+
+    If the file becomes empty after stripping, delete it.
+    If the file does not exist, emit a notice and return.
+    """
+    hook_file = repo_path / ".git" / "hooks" / filename
+
+    if not hook_file.exists():
+        console.print(f"[yellow]No {filename} hook found in {repo_path}[/yellow]")
+        return
+
+    content = hook_file.read_text()
+
+    if sentinel not in content:
+        # Nothing to strip
+        return
+
+    new_content = _strip_sentinel_block(content, sentinel)
 
     if not new_content.strip():
-        # File became empty, delete it
         try:
             hook_file.unlink()
-            console.print(
-                f"[green]Removed git hook from {repo_path}/.git/hooks/post-checkout[/green]"
-            )
+            console.print(f"[green]Removed git hook from {repo_path}/.git/hooks/{filename}[/green]")
         except Exception as e:
             console.print(f"[yellow]Warning:[/yellow] Failed to delete hook file: {e}")
     else:
-        # Write back the filtered content
         try:
             hook_file.write_text(new_content)
-            console.print(
-                f"[green]Removed git hook from {repo_path}/.git/hooks/post-checkout[/green]"
-            )
+            console.print(f"[green]Removed git hook from {repo_path}/.git/hooks/{filename}[/green]")
         except Exception as e:
             console.print(f"[yellow]Warning:[/yellow] Failed to update hook file: {e}")
 
 
+# (filename, sentinel) pairs for all sqlcg-managed hooks
+_HOOK_SENTINELS: list[tuple[str, str]] = [
+    ("post-checkout", "# sqlcg post-checkout hook"),
+    ("post-merge", "# sqlcg post-merge hook"),
+]
+
+
+def _step3_remove_git_hook(repo_path: Path) -> None:
+    """Remove sqlcg sentinel blocks from all managed git hook files.
+
+    Strips both post-checkout and post-merge hooks. Deletes a hook file if it
+    becomes empty after stripping; preserves foreign content otherwise.
+    """
+    for filename, sentinel in _HOOK_SENTINELS:
+        _remove_single_hook(repo_path, filename, sentinel)
+
+
 def _get_db_path() -> str | None:
     """Get the configured database path from environment or default."""
-    db_path = os.getenv("SQLCG_DB_PATH")
-    if db_path:
-        return db_path
+    from sqlcg.core.config import KuzuConfig
 
-    # Default path for kuzu
-    default_path = str(Path.home() / ".sqlcg" / "kuzu.db")
-    return default_path if Path(default_path).exists() else None
+    db_path = str(KuzuConfig.from_env().db_path)
+    return db_path if Path(db_path).exists() else None
 
 
 def _is_kuzu_backend(db_path: str) -> bool:
     """Check if the database is a KùzuDB backend (not Neo4j)."""
     backend = os.getenv("SQLCG_BACKEND", "kuzu").lower()
     return backend in ("kuzu", "")  # Default to kuzu if unset
+
+
+# Candidate skill directory locations to remove (global first, then project-relative)
+# Each entry is a callable(repo_path) -> Path resolving to the sqlcg skill dir.
+_SKILL_DIR_TARGETS = [
+    lambda repo_path: Path.home() / ".claude" / "skills" / "sqlcg",
+    lambda repo_path: repo_path / ".claude" / "skills" / "sqlcg",
+]
+
+
+def _step4_remove_skill(repo_path: Path) -> None:
+    """Remove the sqlcg-owned skill directory at all candidate locations.
+
+    Iterates over the global (~/.claude/skills/sqlcg/) and project-relative
+    (<repo>/.claude/skills/sqlcg/) directories. For each:
+    - If the directory exists, removes it with shutil.rmtree (ignoring errors)
+      and prints a green "Removed" notice.
+    - If the directory does not exist, prints a yellow "not found" notice.
+
+    Only the sqlcg/ subdirectory is ever removed — the parent skills/ dir and
+    any sibling skill directories are left untouched.
+    """
+    any_found = False
+    for target_fn in _SKILL_DIR_TARGETS:
+        skill_dir = target_fn(repo_path)
+        if skill_dir.exists():
+            any_found = True
+            shutil.rmtree(skill_dir, ignore_errors=True)
+            console.print(f"[green]Removed skill directory:[/green] {skill_dir}")
+        else:
+            console.print(f"[yellow]Skill directory not found:[/yellow] {skill_dir}")
+
+    if not any_found:
+        console.print("[yellow]No skill directories found — nothing to remove.[/yellow]")

sqlcg/cli/commands/watch.py

@@ -29,6 +29,17 @@ def watch_cmd(  # noqa: B008
     with get_backend() as backend:
         backend.init_schema()
 
+        # Check schema version — must match current build
+        from sqlcg.core.schema import SCHEMA_VERSION
+
+        stored = backend.get_schema_version()
+        if stored != SCHEMA_VERSION:
+            console.print(
+                f"[red]Database schema is v{stored}; this build requires v{SCHEMA_VERSION}. "
+                "Run 'sqlcg db reset && sqlcg db init' to re-initialize.[/red]"
+            )
+            raise typer.Exit(1)
+
         indexer = Indexer()
 
         # Initial full index
@@ -37,7 +48,9 @@ def watch_cmd(  # noqa: B008
 
         spec = load_ignore_spec(path)
         job_manager = WatchJobManager(indexer, backend, dialect)
-        handler = SqlFileEventHandler(job_manager, backend, spec, path, indexer=indexer)
+        handler = SqlFileEventHandler(
+            job_manager, backend, spec, path, indexer=indexer, dialect=dialect
+        )
         observer = Observer()
         observer.schedule(handler, str(path), recursive=True)
         observer.start()

sqlcg/cli/main.py

@@ -12,6 +12,7 @@ from sqlcg.cli.commands import (
     index,
     install,
     mcp,
+    reindex,
     report,
     uninstall,
     watch,
@@ -23,6 +24,12 @@ QUICK START:
   1. sqlcg db init
   2. sqlcg index <path> --dialect snowflake
   3. sqlcg git install-hooks
+  4. sqlcg install --scope project   # also provisions a Claude skill (SKILL.md)
+
+USING THE MCP TOOLS:
+  Read `sqlcg mcp best-practices` first — it explains the fact/heuristic
+  boundary so heuristic output (dead-code, risk) is never reported as fact.
+  See `sqlcg mcp --help` for all MCP commands.
 
 Note: Binary is `sqlcg`; PyPI package is `sql-code-graph`.
 """
@@ -38,6 +45,7 @@ app.add_typer(git.app, name="git")
 
 # Register single commands
 app.command("index")(index.index_cmd)
+app.command("reindex")(reindex.reindex_cmd)
 app.command("watch")(watch.watch_cmd)
 app.command("gain")(gain.gain_cmd)
 app.command("report")(report.report_cmd)

sqlcg/core/config.py

@@ -15,6 +15,10 @@ class KuzuConfig(BaseModel):
     """Configuration for KùzuDB backend."""
 
     db_path: Path = Field(default_factory=lambda: Path.home() / ".sqlcg" / "graph.db")
+    buffer_pool_size_mb: int = Field(
+        default=0,
+        description="KuzuDB buffer pool size in MB (0 = use KuzuDB default)",
+    )
 
     @classmethod
     def from_env(cls) -> "KuzuConfig":
@@ -24,7 +28,11 @@ class KuzuConfig(BaseModel):
             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()
+        env_buf = os.getenv("SQLCG_BUFFER_POOL_MB")
+        return cls(
+            db_path=Path(env_path) if env_path else Path.home() / ".sqlcg" / "graph.db",
+            buffer_pool_size_mb=int(env_buf) if env_buf else 0,
+        )
 
 
 class Neo4jConfig(BaseModel):
@@ -79,6 +87,178 @@ def get_dialect(path: Path) -> str:
     return "snowflake"
 
 
+def get_schema_aliases(path: Path) -> dict[str, str]:
+    """Get schema alias mappings from .sqlcg.toml.
+
+    Reads [sqlcg.schema_aliases] and returns a lowercased staging-schema →
+    canonical-schema dict.  Use this when a staging area sits under a different
+    schema but the table names are identical, e.g.::
+
+        [sqlcg.schema_aliases]
+        da_tmp = "da"
+        ba_tmp = "ba"
+
+    Any table reference whose schema part matches a key is rewritten to use the
+    canonical schema instead, so ``da_tmp.my_table`` is traced as ``da.my_table``.
+
+    Args:
+        path: Root directory to search for .sqlcg.toml
+
+    Returns:
+        Dict mapping staging schema name (lowercase) to its canonical replacement
+    """
+    config_file = Path(path) / ".sqlcg.toml"
+    if config_file.exists():
+        try:
+            with open(config_file, "rb") as f:
+                config = tomllib.load(f)
+            raw = config.get("sqlcg", {}).get("schema_aliases", {})
+            if isinstance(raw, dict):
+                return {k.lower(): v for k, v in raw.items() if isinstance(v, str)}
+        except Exception:
+            pass
+    return {}
+
+
+def get_noise_filter_patterns(path: Path) -> list[str]:
+    """Get backup table ignore patterns from .sqlcg.toml.
+
+    Reads [sqlcg.noise_filter] -> ignore_table_patterns (a list of glob strings)
+    from .sqlcg.toml. Returns the list lowercased. When the key is absent,
+    returns a built-in default list::
+
+        [sqlcg.noise_filter]
+        ignore_table_patterns = ["*_bck", "*_bck_us", "*_bck_[0-9]*"]
+
+    Args:
+        path: Root directory to search for .sqlcg.toml
+
+    Returns:
+        List of glob patterns (all lowercased). Defaults to built-in backup patterns.
+    """
+    default_patterns = [
+        "*_bck",
+        "*_bck_us",
+        "*_bck_[0-9]*",
+        "*_backup",
+        "*_backup_[0-9]*",
+    ]
+    config_file = Path(path) / ".sqlcg.toml"
+    if config_file.exists():
+        try:
+            with open(config_file, "rb") as f:
+                config = tomllib.load(f)
+            raw = config.get("sqlcg", {}).get("noise_filter", {}).get("ignore_table_patterns")
+            if isinstance(raw, list):
+                return [p.lower() if isinstance(p, str) else p for p in raw]
+        except Exception:
+            pass
+    return default_patterns
+
+
+def get_ignored_tables(path: Path) -> list[str]:
+    """Get explicitly-ignored qualified table names from .sqlcg.toml.
+
+    Complements ``get_noise_filter_patterns`` (glob patterns) with an exact
+    qualified-name list, for specific tables that do not follow a backup naming
+    convention but should still be dropped from tool answers — e.g. a
+    load-control / delta-bookkeeping table::
+
+        [sqlcg.noise_filter]
+        ignored_tables = ["ma.rtetl_delta", "ctl.load_log"]
+
+    Names are matched exactly (case-insensitive) against ``schema.table``. The
+    lineage engine still records these as real edges; this only lets a user
+    declare them noise in config rather than baking the judgment into code.
+
+    Args:
+        path: Root directory to search for .sqlcg.toml
+
+    Returns:
+        List of qualified table names (all lowercased). Defaults to an empty list.
+    """
+    config_file = Path(path) / ".sqlcg.toml"
+    if config_file.exists():
+        try:
+            with open(config_file, "rb") as f:
+                config = tomllib.load(f)
+            raw = config.get("sqlcg", {}).get("noise_filter", {}).get("ignored_tables")
+            if isinstance(raw, list):
+                return [t.lower() for t in raw if isinstance(t, str)]
+        except Exception:
+            pass
+    return []
+
+
+def get_ignore_table_regexes(path: Path) -> list[str]:
+    """Get table-exclusion regexes from .sqlcg.toml.
+
+    Complements ``get_noise_filter_patterns`` (anchored fnmatch globs) and
+    ``get_ignored_tables`` (exact names) with full regular expressions, for
+    backup conventions the globs cannot express — e.g. a ``_bck`` marker that
+    can appear anywhere in the name, not just as a suffix::
+
+        [sqlcg.noise_filter]
+        ignore_table_regexes = ["_bck", "_tmp_[0-9]{8}"]
+
+    Each pattern is matched (``re.search``, case-insensitive) against the full
+    qualified ``schema.table`` name, so an unanchored ``_bck`` excludes
+    ``ba.foo_bck`` and ``da.bar_bck_archive`` alike (the latter is missed by the
+    suffix-anchored ``*_bck`` glob). The
+    lineage engine still records these as real edges; this only lets a user
+    declare them noise in config rather than baking the judgment into code.
+
+    Args:
+        path: Root directory to search for .sqlcg.toml
+
+    Returns:
+        List of regex strings (kept verbatim — not lowercased, so character
+        classes survive). Defaults to an empty list.
+    """
+    config_file = Path(path) / ".sqlcg.toml"
+    if config_file.exists():
+        try:
+            with open(config_file, "rb") as f:
+                config = tomllib.load(f)
+            raw = config.get("sqlcg", {}).get("noise_filter", {}).get("ignore_table_regexes")
+            if isinstance(raw, list):
+                return [r for r in raw if isinstance(r, str)]
+        except Exception:
+            pass
+    return []
+
+
+def get_presentation_prefixes(path: Path) -> list[str]:
+    """Get presentation-facing schema prefixes from .sqlcg.toml.
+
+    Reads [sqlcg.presentation] -> schema_prefixes (a list of strings) from
+    .sqlcg.toml. Returns the list lowercased. **Defaults to an empty list** when
+    the key is absent — when unset, presentation-facing detection is simply off
+    (correct generic behaviour for any user). No schema prefix is hardcoded in
+    shipped code; a DWH that wants ``ia_`` flagged must declare it::
+
+        [sqlcg.presentation]
+        schema_prefixes = ["ia_"]
+
+    Args:
+        path: Root directory to search for .sqlcg.toml
+
+    Returns:
+        List of schema prefixes (all lowercased). Defaults to an empty list.
+    """
+    config_file = Path(path) / ".sqlcg.toml"
+    if config_file.exists():
+        try:
+            with open(config_file, "rb") as f:
+                config = tomllib.load(f)
+            raw = config.get("sqlcg", {}).get("presentation", {}).get("schema_prefixes")
+            if isinstance(raw, list):
+                return [p.lower() for p in raw if isinstance(p, str)]
+        except Exception:
+            pass
+    return []
+
+
 def get_backend() -> "GraphBackend":
     """Get a graph backend instance respecting the SQLCG_BACKEND env var.
 
@@ -94,7 +274,10 @@ def get_backend() -> "GraphBackend":
         from sqlcg.core.kuzu_backend import KuzuBackend
 
         kuzu_cfg = KuzuConfig.from_env()
-        return KuzuBackend(str(kuzu_cfg.db_path))
+        return KuzuBackend(
+            str(kuzu_cfg.db_path),
+            buffer_pool_size_mb=kuzu_cfg.buffer_pool_size_mb,
+        )
     elif backend_type == "neo4j":
         from sqlcg.core.neo4j_backend import Neo4jBackend
 

sqlcg/core/graph_db.py

@@ -67,6 +67,52 @@ class GraphBackend(ABC):
             properties: Dict of properties to set/update on the relationship
         """
 
+    @abstractmethod
+    def upsert_nodes_bulk(
+        self,
+        label: str,
+        rows: list[dict[str, Any]],
+    ) -> None:
+        """Bulk-upsert nodes of one label in a single backend round-trip.
+
+        Each row dict must contain the primary-key field for `label` (see _pk_field)
+        plus any other properties to SET. All rows must share the same property-key
+        set; backends MAY raise if rows are heterogeneous (KuzuBackend does).
+
+        Idempotent MERGE semantics, identical to upsert_node per row.
+
+        Args:
+            label: Node label (e.g., NodeLabel.COLUMN)
+            rows: List of property dicts. Empty list is a no-op.
+        """
+
+    @abstractmethod
+    def upsert_edges_bulk(
+        self,
+        src_label: str,
+        dst_label: str,
+        rel_type: str,
+        rows: list[dict[str, Any]],
+    ) -> None:
+        """Bulk-upsert edges of one (src_label, rel_type, dst_label) triple.
+
+        Each row dict must contain:
+          - "src_key": source primary-key value (matches src_label _pk_field)
+          - "dst_key": destination primary-key value (matches dst_label _pk_field)
+          - Any additional keys are set as edge properties.
+
+        Idempotent MERGE semantics, identical to upsert_edge per row. Rows whose
+        src or dst node does not exist are silently skipped by KuzuDB's MERGE
+        semantics — callers must ensure node upserts happen first within the same
+        transaction (see indexer ordering rules in _upsert_parsed_file).
+
+        Args:
+            src_label: Source node label
+            dst_label: Destination node label
+            rel_type: Relationship type
+            rows: List of edge property dicts. Empty list is a no-op.
+        """
+
     @abstractmethod
     def run_read(self, query: str, params: dict[str, Any]) -> list[dict[str, Any]]:
         """Execute a read-only query and return results.
@@ -112,6 +158,25 @@ class GraphBackend(ABC):
             The schema version string, or None if not set.
         """
 
+    @abstractmethod
+    def set_indexed_sha(self, sha: str) -> None:
+        """Persist the git SHA of the last successful index.
+
+        Written by index_repo on success and by resync_changed on success.
+
+        Args:
+            sha: Git commit SHA string (e.g. from git rev-parse HEAD).
+        """
+
+    @abstractmethod
+    def get_indexed_sha(self) -> str | None:
+        """Retrieve the git SHA of the last successful index.
+
+        Returns:
+            The stored SHA string, or None if never set (repo pre-dates this
+            feature, or the DB was freshly initialised).
+        """
+
     @abstractmethod
     def close(self) -> None:
         """Close the database connection."""