sql-code-graph 1.0.0__py3-none-any.whl → 1.0.2__py3-none-any.whl

{sql_code_graph-1.0.0.dist-info → sql_code_graph-1.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-code-graph
-Version: 1.0.0
+Version: 1.0.2
 Summary: SQL code graph analyzer and lineage tracer
 Project-URL: Homepage, https://github.com/Warhorze/sql-code-graph
 Project-URL: Repository, https://github.com/Warhorze/sql-code-graph

{sql_code_graph-1.0.0.dist-info → sql_code_graph-1.0.2.dist-info}/RECORD

@@ -1,22 +1,22 @@
-sqlcg/__init__.py,sha256=2lT2oiKX19arg1oTOFf13dXA3qyyQNpRevdvKHZIOp4,115
+sqlcg/__init__.py,sha256=hGOhwTAVTaRm7PjbaSQVCLvnF7rOGZZNdMqv0IoQdYg,115
 sqlcg/__main__.py,sha256=1YoFLcqEgTwYq1J3TbUwpkdG0zeeLIf2fJvwWI-CLFU,109
 sqlcg/cli/__init__.py,sha256=W8fD0LpMq2xm_5WKGNMvJh2WBL1ho5E8hUeAqXQYT1g,28
 sqlcg/cli/main.py,sha256=WmdTjsOlz1ozi2Y3Aq4ezR_FCRl-Lc1YOKw3_d48dlY,1650
 sqlcg/cli/commands/__init__.py,sha256=oSHtr6VD-jNubOjuCQyZj2tBppjMEpQDh-IGQ8of9eA,30
-sqlcg/cli/commands/analyze.py,sha256=kfcySSjc_UhSsOsJg7o5VD7TH4v72KVzol7Cdn2EuOU,4127
+sqlcg/cli/commands/analyze.py,sha256=PFQD29_VAtJ-wghYLsHRINp8VlnOVl1WlOdbAdcWz1E,8091
 sqlcg/cli/commands/db.py,sha256=Yd4ZDz1BFwjO4Lyt3NefQnowkjdUxFDFmsPykBVH2Pk,6518
-sqlcg/cli/commands/find.py,sha256=4cEWQ0otxNIzzwwzZ0WB_Tms0EoKzcFfhB3FJt8Q5V4,2025
+sqlcg/cli/commands/find.py,sha256=P2OFI0O_-F4W5-oy5KObXUHI7gNTkJRtDSZ59xTKE9Y,2672
 sqlcg/cli/commands/gain.py,sha256=bOvia7CVla_fESrDEdftYze8Mm0xDio3SpCzIyoXg7A,8925
 sqlcg/cli/commands/git.py,sha256=96hmWYd861FC8RZqPQ_eBG8yLXSXaB9SLxmuwx00nWU,3347
-sqlcg/cli/commands/index.py,sha256=6f-kaoY5roY4DDvEOi_HrDnBG9Jrqy0_A47gsxZsNUQ,7421
-sqlcg/cli/commands/install.py,sha256=mNVXdGlQ4JtCaaibuzU-inf519T97mC-Nj9K-G2gMQY,7525
-sqlcg/cli/commands/mcp.py,sha256=H1j6b5Tqr5VXja2GafgD5sJD6hZ5rsgfPwIikK1PZqc,1903
-sqlcg/cli/commands/reindex.py,sha256=iZXxYGI2m2wxkvIA1mB9uvOEp66QaT5zF5TGd0OpqlU,6275
+sqlcg/cli/commands/index.py,sha256=Sgrg5MaQWfQzbX3e3Wcsfd8BEWDGuBm5l5vynpJsRzA,9801
+sqlcg/cli/commands/install.py,sha256=KNABvrLbamPyYnmnVdCaM_MNezbDc-pr6IkignCWI8k,9186
+sqlcg/cli/commands/mcp.py,sha256=cfi7D-RgEPUKdfUbsJC2iKImKOnHQvWxCLfwYIPdhdE,2174
+sqlcg/cli/commands/reindex.py,sha256=J9gpaxSzJ1mTdOJWh7WSLskbRF9f_2EMWnUFF4VOtVU,6387
 sqlcg/cli/commands/report.py,sha256=JU0qjyMxwOukE7bN3XvvIzOI7zMg_Gsnvk_8F6pKNpA,4915
 sqlcg/cli/commands/uninstall.py,sha256=IYwQaqnMmmzW0Nlls40wD-L3tVkMgKIMRXUkcXPMUc4,9398
 sqlcg/cli/commands/watch.py,sha256=7N6c-QuvxAEGHzDZ0C3CU2BkHSraZW9YtgoFnz7SaQo,2373
 sqlcg/core/__init__.py,sha256=uNsJCrCMVWVT80sHPtI_f39BYqIf5N0i6LSq8x8HsyI,283
-sqlcg/core/config.py,sha256=em9gYtau2hu-scWzZk4CSZh4L8r9ZymgmH_2BspqsQw,9773
+sqlcg/core/config.py,sha256=YCq4OayvBSNXsYtOh3yZ-W6fyJBLwYunORDo2TPCU9s,10179
 sqlcg/core/graph_db.py,sha256=gFiHjfVeRHp2FS3yRThDgCWFkugOQD065IvEqN6apg4,7881
 sqlcg/core/jobs.py,sha256=Je-fCdSKRgiSsv1W8SgNAlp36a7t7-pJZ-qKPbka9OE,3298
 sqlcg/core/kuzu_backend.py,sha256=ziHt-AB9sEZY7qB8whseWFicbTfOZaNOxcNVKhjii5Y,16587
@@ -27,10 +27,10 @@ sqlcg/core/schema.cypher,sha256=UWYsPMRgkn6HOlPZ3rl6BfY5hzKQKP5RGPaZg4NTZFY,2515
 sqlcg/core/schema.py,sha256=9jBgJwuvfjLq2xC5B0NUyZZYxhqTb0LO0YzxcPM-gVM,1301
 sqlcg/indexer/__init__.py,sha256=Wh20Unz2OHs1oIyWLrpurPAasF0BET2g4iXtNk7mh2U,56
 sqlcg/indexer/dbt_adapter.py,sha256=EB5x1WU5Z9d-I97ADDj88S_hG1C4z4nbrv8JUCzXfy8,686
-sqlcg/indexer/error_classify.py,sha256=eWmc9WdOFe9kY_DMgKL0vv9gfcKnFw8e8U7cpUUw9wU,5139
-sqlcg/indexer/git_delta.py,sha256=V7WiNgiYPRo97K_mB3ymkJDZGoFExqwTZ2ut0Nqua5o,4383
-sqlcg/indexer/indexer.py,sha256=Jes0SybIDXLWQlWbRrDAbxVfJ7OsdS3PDAVSoRcv3Tc,50605
-sqlcg/indexer/pool.py,sha256=Q9DQmgUsSeKL1S-gNAzMbCNPGI9WsG6Nmt_noh_O8M8,16069
+sqlcg/indexer/error_classify.py,sha256=MYjPVprwT-ARPjBCyCzu2F9DSrZfnTVtVIoBgm8s4H8,5329
+sqlcg/indexer/git_delta.py,sha256=P-QM4vnVURT2KLiE6u3cQynRUF-mTH13cbB4I20YHPQ,4468
+sqlcg/indexer/indexer.py,sha256=0B0BCUaLPdV9XtlCzhqR3hwHyD3w83o-tYG7yNr18Yo,50507
+sqlcg/indexer/pool.py,sha256=BTYx-pBe6zwUG89MHh0X7nzGNVlsHN-GjovYKanVI1s,18553
 sqlcg/indexer/walker.py,sha256=C__JuDcTzKxFqVjGFRr5cj9hgxvf8zffTz-0HMn1qTY,1746
 sqlcg/indexer/watcher.py,sha256=mJQq1LASRLKKwhz0WhCUWPLLqyPR2_-FD_8efYU6gE8,8442
 sqlcg/lineage/__init__.py,sha256=Da1DlYwtK13WHv_RnHjAtNkHTOuFbhxqCjT1Le7DsWM,46
@@ -40,7 +40,7 @@ sqlcg/metrics/__init__.py,sha256=hLJ6wm4St8qqYwKh3o9QG7lcEt1BEYM31ccqO9tGpIg,133
 sqlcg/metrics/store.py,sha256=BaMf7QYTmYMlX_Jzi1GNU8R2sMVkWdn07f-ZSndtcNk,8879
 sqlcg/parsers/__init__.py,sha256=AamA8wBbDZV9_zEtZCI4Hyen5UAVKHmBwjTghTt2PZE,785
 sqlcg/parsers/ansi_parser.py,sha256=KruZn5CYjpktKmMRVWackshRI_AR6ehc-ReCsDeWNkQ,14321
-sqlcg/parsers/base.py,sha256=aw-gueAMdt551peUY0g7lWbswQLPWx0FDCK4RDfUjDE,43205
+sqlcg/parsers/base.py,sha256=cSHlXwiSNu77TZI6_p1nRevbRTcBc1t5v8N_aKR7uB4,49117
 sqlcg/parsers/bigquery_parser.py,sha256=mOnWTfXB_Dp4JwFE1PVYOB6CDPf5nYE0Dea8kJCl9uQ,2827
 sqlcg/parsers/postgres_parser.py,sha256=lYfUpQY6j4Qm7ndXBtXbgPoGzYqYddWt5YeFnWKdA6I,946
 sqlcg/parsers/registry.py,sha256=LXy1F6rqQI6VdxpRvZg_tNpoEucW3mXZHYBMlMONbX4,1496
@@ -50,14 +50,14 @@ sqlcg/server/__init__.py,sha256=n4wuNE7xyJIJxJZBtmtdccCMQfvTdF-IqIaZVbC4FC4,35
 sqlcg/server/exceptions.py,sha256=EONw34icOByCTpppSQrvQBW6asc4hfqaGDCAFjv96II,469
 sqlcg/server/models.py,sha256=dv4SM_o-aY8kUFIbCtj0l8ceMsfyvQtXCWPm4Ek_-14,16432
 sqlcg/server/noise_filter.py,sha256=idSBGgdKWWccJdpOo9qgbM2350Oew-2l5W6Yc9GYQqY,6337
-sqlcg/server/server.py,sha256=2EwKGehcIdKqCjZagbv8VrvnVCp-D5Lh-z38FFHRcN8,1723
+sqlcg/server/server.py,sha256=mDAW_Zmk3Sp2sApw3Gw3veCqJe7waw-sioQyKZBn9ng,3774
 sqlcg/server/skill.py,sha256=siAtrRdFHQnASe9nl33MvkTXXt9EgCB8id5i9AUq4XU,10718
-sqlcg/server/tools.py,sha256=Jh16fefXMmw0mYUejoIMAXlJoPAaQoUbgrCghsmHNLk,54892
+sqlcg/server/tools.py,sha256=mSoYZRI7F5ZmdTcG-BnY6ULzrz3Y7qIFe3cHTVWVyMs,57785
 sqlcg/utils/__init__.py,sha256=--iqt5ThTXmT8Wz7da8hs3n0zDfYPl8P-z5OgRJ_77E,154
 sqlcg/utils/hashing.py,sha256=H25-sYfxHKb3_IERFnHyAIYNiXN470Oqo5sJT_D3YOA,438
-sqlcg/utils/ignore.py,sha256=NfInsHPGubfKFJQraH-wE7ATPb5Be_Igu5mIh7p21cU,973
+sqlcg/utils/ignore.py,sha256=wJjwa0mjnQ_xJExOUxk25y00g065XmmzJapqV3ifD5o,1151
 sqlcg/utils/logging.py,sha256=u0fCmYsLj9o81vawm3xZTHaw68GQYVm7JxG-gP81u8A,840
-sql_code_graph-1.0.0.dist-info/METADATA,sha256=HQdFHBzEKTlPlqnwRCT9n0iKrmWqkmM5mhM3fOi5lvo,12806
-sql_code_graph-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sql_code_graph-1.0.0.dist-info/entry_points.txt,sha256=Wfe49sVzV9p4eVFGo5RxcV-frr3HOP0yzzst8JBxQLQ,46
-sql_code_graph-1.0.0.dist-info/RECORD,,
+sql_code_graph-1.0.2.dist-info/METADATA,sha256=aikAv-KoUOGfgYo3-htWLyq61x1PE6bC1Onn_TNAuvE,12806
+sql_code_graph-1.0.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sql_code_graph-1.0.2.dist-info/entry_points.txt,sha256=Wfe49sVzV9p4eVFGo5RxcV-frr3HOP0yzzst8JBxQLQ,46
+sql_code_graph-1.0.2.dist-info/RECORD,,

sqlcg/__init__.py

@@ -1,5 +1,5 @@
 """SQL Code Graph - SQL lineage and dependency analysis tool."""
 
-__version__ = "1.0.0"
+__version__ = "1.0.2"
 
 __all__ = ["__version__"]

sqlcg/cli/commands/analyze.py

@@ -1,5 +1,9 @@
 """Analyze command for lineage analysis."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 import typer
 from rich.console import Console
 from rich.table import Table
@@ -7,6 +11,9 @@ from rich.table import Table
 from sqlcg.core.config import get_backend
 from sqlcg.core.schema import NodeLabel, RelType
 
+if TYPE_CHECKING:
+    from sqlcg.server.noise_filter import NoiseFilter
+
 app = typer.Typer(help="Lineage analysis")
 console = Console()
 
@@ -15,6 +22,7 @@ console = Console()
 def upstream(  # noqa: B008
     ref: str = typer.Argument(..., help="Column reference"),  # noqa: B008
     depth: int = typer.Option(5, "--depth", help="Maximum traversal depth"),  # noqa: B008
+    raw: bool = typer.Option(False, "--raw", help="Disable noise filtering on results"),  # noqa: B008
 ) -> None:
     """Trace upstream column lineage."""
     # Bounds check for depth to prevent performance DoS
@@ -29,6 +37,28 @@ def upstream(  # noqa: B008
             "RETURN src.id AS id LIMIT 100",
             {"ref": ref},
         )
+        if not results and len(ref.split(".")) >= 3:
+            bare = _bare_ref(ref)
+            fallback_results = backend.run_read(
+                f"MATCH p=(c:{NodeLabel.COLUMN} {{id: $bare}})"
+                f"<-[:{RelType.COLUMN_LINEAGE}*1..{depth}]-(src) "
+                "RETURN src.id AS id LIMIT 100",
+                {"bare": bare},
+            )
+            if fallback_results:
+                console.print(
+                    f"[yellow]Hint:[/yellow] No results for '{ref}'. "
+                    f"Found {len(fallback_results)} edge(s) under bare name '{bare}'. "
+                    "The INSERT target may have been indexed without a schema prefix. "
+                    "Multiple tables with the same unqualified name in different schemas "
+                    "would all match — re-index with an explicit schema for precise results."
+                )
+                results = fallback_results
+        if not raw:
+            from sqlcg.server.noise_filter import NoiseFilter
+
+            nf = NoiseFilter.from_config()  # repo_root=None → falls back to Path.cwd()
+            results = _filter_column_results(results, nf)
         _print_table(results, ["id"])
 
 
@@ -36,6 +66,7 @@ def upstream(  # noqa: B008
 def downstream(  # noqa: B008
     ref: str = typer.Argument(..., help="Column reference"),  # noqa: B008
     depth: int = typer.Option(5, "--depth", help="Maximum traversal depth"),  # noqa: B008
+    raw: bool = typer.Option(False, "--raw", help="Disable noise filtering on results"),  # noqa: B008
 ) -> None:
     """Trace downstream column lineage."""
     # Bounds check for depth to prevent performance DoS
@@ -50,6 +81,28 @@ def downstream(  # noqa: B008
             "RETURN dst.id AS id LIMIT 100",
             {"ref": ref},
         )
+        if not results and len(ref.split(".")) >= 3:
+            bare = _bare_ref(ref)
+            fallback_results = backend.run_read(
+                f"MATCH p=(c:{NodeLabel.COLUMN} {{id: $bare}})"
+                f"-[:{RelType.COLUMN_LINEAGE}*1..{depth}]->(dst) "
+                "RETURN dst.id AS id LIMIT 100",
+                {"bare": bare},
+            )
+            if fallback_results:
+                console.print(
+                    f"[yellow]Hint:[/yellow] No results for '{ref}'. "
+                    f"Found {len(fallback_results)} edge(s) under bare name '{bare}'. "
+                    "The INSERT target may have been indexed without a schema prefix. "
+                    "Multiple tables with the same unqualified name in different schemas "
+                    "would all match — re-index with an explicit schema for precise results."
+                )
+                results = fallback_results
+        if not raw:
+            from sqlcg.server.noise_filter import NoiseFilter
+
+            nf = NoiseFilter.from_config()  # repo_root=None → falls back to Path.cwd()
+            results = _filter_column_results(results, nf)
         _print_table(results, ["id"])
 
 
@@ -106,6 +159,43 @@ def unused(
         _print_table(results, ["qualified"])
 
 
+def _bare_ref(ref: str) -> str:
+    """Strip schema prefix from a ref string, keeping table.column.
+
+    For a 3-part ref ("mart.fact_t.amount") this returns "fact_t.amount".
+    For a 2-part ref ("fact_t.amount") this returns the ref unchanged.
+    Never uses rsplit — that would yield only the column name for 3-part refs.
+    """
+    parts = ref.split(".")
+    if len(parts) >= 3:
+        return ".".join(parts[1:])  # drop schema, keep table.column
+    return ref  # already bare (no schema prefix)
+
+
+def _col_id_to_table(col_id: str) -> str:
+    """Extract the table-qualified part from a column ID (schema.table.col → schema.table).
+
+    Column IDs follow the format: schema.table.column or table.column.
+    The table part is everything except the last component.
+
+    Args:
+        col_id: A column ID string from the graph.
+
+    Returns:
+        The table-qualified portion (all but the last dotted component).
+    """
+    parts = col_id.rsplit(".", 1)
+    return parts[0] if len(parts) == 2 else col_id
+
+
+def _filter_column_results(
+    results: list[dict],
+    nf: NoiseFilter,  # type: ignore[name-defined]
+) -> list[dict]:
+    """Filter column-ID result rows by NoiseFilter, dropping rows whose table is noise."""
+    return [r for r in results if not nf.is_noise(_col_id_to_table(r["id"]))]
+
+
 def _print_table(rows: list[dict], columns: list[str]) -> None:
     """Print results as a Rich table."""
     if not rows:

sqlcg/cli/commands/find.py

@@ -14,14 +14,24 @@ console = Console()
 @app.command("table")
 def find_table(  # noqa: B008
     name: str = typer.Argument(..., help="Table name to search for"),  # noqa: B008
+    raw: bool = typer.Option(False, "--raw", help="Disable noise filtering on results"),  # noqa: B008
 ) -> None:
     """Find a table by name."""
+    name = name.lower()  # graph keys are lowercased at index time (C2 normalization)
     with get_backend() as backend:
         results = backend.run_read(
             f"MATCH (t:{NodeLabel.TABLE}) WHERE t.qualified CONTAINS $name "
             "RETURN t.qualified AS qualified, t.kind AS kind LIMIT 50",
             {"name": name},
         )
+        if not raw:
+            from sqlcg.server.noise_filter import NoiseFilter
+
+            nf = NoiseFilter.from_config()  # repo_root=None → falls back to Path.cwd()
+            ids = [r["qualified"] for r in results]
+            kept, _ = nf.filter_nodes(ids)
+            kept_set = set(kept)
+            results = [r for r in results if r["qualified"] in kept_set]
         _print_table(results, ["qualified", "kind"])
 
 
@@ -30,6 +40,7 @@ def find_column(  # noqa: B008
     ref: str = typer.Argument(..., help="Column reference (table.column)"),  # noqa: B008
 ) -> None:
     """Find a column by table.column reference."""
+    ref = ref.lower()  # graph keys are lowercased at index time (C2 normalization)
     with get_backend() as backend:
         results = backend.run_read(
             f"MATCH (c:{NodeLabel.COLUMN}) WHERE c.id CONTAINS $ref RETURN c.id AS id LIMIT 50",

sqlcg/cli/commands/index.py

@@ -14,7 +14,7 @@ from rich.progress import (
     TimeRemainingColumn,
 )
 
-from sqlcg.core.config import get_backend, get_db_path, get_dialect
+from sqlcg.core.config import KuzuConfig, get_backend, get_db_path, get_dialect
 from sqlcg.indexer.indexer import Indexer
 
 console = Console()
@@ -54,6 +54,9 @@ def index_cmd(  # noqa: B008
     quiet: bool = typer.Option(  # noqa: B008
         False, "--quiet", "-q", help="Suppress summary console output"
     ),
+    verbose: bool = typer.Option(  # noqa: B008
+        False, "--verbose", "-v", help="Print parse warnings to stderr instead of log file"
+    ),
     debug: bool = typer.Option(  # noqa: B008
         False, "--debug", help="Show detailed log output during indexing"
     ),
@@ -68,11 +71,40 @@ def index_cmd(  # noqa: B008
     """
 
     import logging
+    import sys
 
     level = logging.DEBUG if debug else logging.CRITICAL
     logging.getLogger("sqlcg").setLevel(level)
     logging.getLogger("sqlglot").setLevel(level)
 
+    # Route parse warnings to stderr (--verbose) or to the configured log file.
+    sqlcg_log = logging.getLogger("sqlcg")
+
+    class _CountingHandler(logging.Handler):
+        """Counts WARNING+ records emitted during indexing."""
+
+        def __init__(self) -> None:
+            super().__init__(logging.WARNING)
+            self.count = 0
+
+        def emit(self, record: logging.LogRecord) -> None:
+            self.count += 1
+
+    _counter = _CountingHandler()
+    sqlcg_log.addHandler(_counter)
+
+    if verbose:
+        _warn_handler: logging.Handler = logging.StreamHandler(sys.stderr)
+        _warn_handler.setLevel(logging.WARNING)
+        sqlcg_log.addHandler(_warn_handler)
+        _warn_log_path = None
+    else:
+        _warn_log_path = KuzuConfig.from_env().log_path
+        _warn_log_path.parent.mkdir(parents=True, exist_ok=True)
+        _warn_handler = logging.FileHandler(_warn_log_path)
+        _warn_handler.setLevel(logging.WARNING)
+        sqlcg_log.addHandler(_warn_handler)
+
     # Set buffer pool size via env var if specified
     if buffer_pool_size > 0:
         os.environ["SQLCG_BUFFER_POOL_MB"] = str(buffer_pool_size)
@@ -84,6 +116,45 @@ def index_cmd(  # noqa: B008
     db_path = get_db_path()
     db_path.parent.mkdir(parents=True, exist_ok=True)
 
+    try:
+        _run_index(
+            path=path,
+            dialect=dialect,
+            dbt_manifest=dbt_manifest,
+            timeout_per_file=timeout_per_file,
+            no_ddl=no_ddl,
+            quiet=quiet,
+            batch_size=batch_size,
+            profile=profile,
+        )
+    except KeyboardInterrupt:
+        # The backend context manager (inside _run_index) has already closed the
+        # KuzuDB connection and released the lock by the time we get here.
+        console.print("\n[yellow]Interrupted — no partial graph written. Re-run to index.[/yellow]")
+        raise typer.Exit(130) from None
+    finally:
+        sqlcg_log.removeHandler(_warn_handler)
+        sqlcg_log.removeHandler(_counter)
+        _warn_handler.close()
+
+    if not verbose and not quiet and _counter.count > 0 and _warn_log_path is not None:
+        console.print(
+            f"[yellow]Parse warnings written to {_warn_log_path} "
+            "— use --verbose to show here.[/yellow]"
+        )
+
+
+def _run_index(
+    *,
+    path: Path,
+    dialect: str | None,
+    dbt_manifest: Path | None,
+    timeout_per_file: int,
+    no_ddl: bool,
+    quiet: bool,
+    batch_size: int,
+    profile: bool,
+) -> None:
     with get_backend() as backend:
         backend.init_schema()
 

sqlcg/cli/commands/install.py

@@ -1,8 +1,19 @@
-"""Install sqlcg as an MCP server in Claude Code."""
+"""Install sqlcg as an MCP server in Claude Code.
+
+Write path (in priority order):
+  1. ``claude mcp add -s user sql-code-graph <cmd> <args>``  — the official
+     Claude Code CLI write path (reads from ~/.claude.json under the hood).
+  2. Fallback: write ``~/.claude.json`` directly under mcpServers.user when
+     the ``claude`` binary is not found or returns non-zero.
+
+The previous target (~/.claude/settings.json) was incorrect — Claude Code does
+NOT read MCP servers from that file. See ARCHITECTURE_REVIEW.md §9.2.
+"""
 
 import json
 import os
 import shutil
+import subprocess
 import sys
 from pathlib import Path
 
@@ -11,7 +22,6 @@ from rich.console import Console
 
 console = Console()
 
-_SETTINGS_PATH = Path.home() / ".claude" / "settings.json"
 _SERVER_KEY = "sql-code-graph"
 
 
@@ -28,7 +38,10 @@ def install_cmd(
         help="Repository root for --scope project (default: current directory).",
     ),
 ) -> None:
-    """Register sqlcg as an MCP server in Claude Code (~/.claude/settings.json).
+    """Register sqlcg as an MCP server in Claude Code.
+
+    Runs ``claude mcp add -s user sql-code-graph <cmd> <args>`` when the
+    ``claude`` CLI is on PATH; otherwise writes ~/.claude.json directly.
 
     Also provisions a Claude skill file (SKILL.md) at the chosen location.
     Pass --scope project or --scope global to specify where the skill is written.
@@ -39,68 +52,81 @@ def install_cmd(
     resolved_scope = _resolve_scope(scope)
 
     if shutil.which("sqlcg"):
-        entry: dict = {"command": "sqlcg", "args": ["mcp", "start"]}
+        cmd_parts = ["sqlcg", "mcp", "start"]
     elif shutil.which("uvx"):
-        entry = {"command": "uvx", "args": ["sql-code-graph", "mcp", "start"]}
+        cmd_parts = ["uvx", "sql-code-graph", "mcp", "start"]
     else:
         console.print("[red]Error:[/red] Neither 'sqlcg' nor 'uvx' found on PATH.")
         raise typer.Exit(1)
 
-    settings_path = _SETTINGS_PATH
-    if settings_path.exists():
+    entry: dict = {"command": cmd_parts[0], "args": cmd_parts[1:]}
+
+    if dry_run:
+        claude_bin = shutil.which("claude")
+        if claude_bin:
+            console.print("[dim]--dry-run: would run:[/dim]")
+            console.print(f"  claude mcp add -s user {_SERVER_KEY} {' '.join(cmd_parts)}")
+        else:
+            claude_json = Path.home() / ".claude.json"
+            console.print("[dim]--dry-run: would write to ~/.claude.json:[/dim]")
+            _preview_claude_json(claude_json, entry)
+        _provision_skill(resolved_scope, repo, dry_run=True)
+        return
+
+    # --- Try official claude CLI first ---
+    claude_bin = shutil.which("claude")
+    if claude_bin:
+        proc = subprocess.run(
+            ["claude", "mcp", "add", "-s", "user", _SERVER_KEY] + cmd_parts,
+            capture_output=True,
+            text=True,
+        )
+        if proc.returncode == 0:
+            console.print(f"[green]Configured:[/green] {_SERVER_KEY} via `claude mcp add`")
+            console.print("\nRestart Claude Code to pick up the new MCP server.")
+            _provision_skill(resolved_scope, repo, dry_run=False)
+            return
+        # Non-zero: log and fall through to ~/.claude.json fallback
+        console.print(
+            f"[yellow]Warning:[/yellow] `claude mcp add` returned rc={proc.returncode}; "
+            "falling back to ~/.claude.json write."
+        )
+        if proc.stderr:
+            console.print(f"[dim]{proc.stderr.strip()}[/dim]")
+
+    # --- Fallback: write ~/.claude.json directly ---
+    claude_json = Path.home() / ".claude.json"
+    if claude_json.exists():
         try:
-            settings: dict = json.loads(settings_path.read_text())
+            data: dict = json.loads(claude_json.read_text())
         except (json.JSONDecodeError, OSError, TypeError):
             console.print(
-                f"[yellow]Warning:[/yellow] {settings_path} contains invalid JSON — "
+                f"[yellow]Warning:[/yellow] {claude_json} contains invalid JSON — "
                 "mcpServers key will be added"
             )
-            settings = {}
+            data = {}
     else:
-        settings = {}
-
-    mcp_servers: dict = settings.setdefault("mcpServers", {})
+        data = {}
 
-    existing_entry = mcp_servers.get(_SERVER_KEY)
-    if existing_entry == entry:
-        cmd_str = f"{entry['command']} {' '.join(entry['args'])}"
-        console.print(f"[green]Already configured:[/green] {_SERVER_KEY} → {cmd_str}")
-        # Still provision the skill even when MCP entry already exists
-        _provision_skill(resolved_scope, repo, dry_run)
+    existing = data.get("mcpServers", {}).get("user", {}).get(_SERVER_KEY)
+    if existing == entry:
+        console.print(f"[green]Already configured:[/green] {_SERVER_KEY} (in ~/.claude.json)")
+        _provision_skill(resolved_scope, repo, dry_run=False)
         return
 
-    # Print upgrade notice if switching from uvx to sqlcg
-    if (
-        existing_entry
-        and existing_entry.get("command") == "uvx"
-        and entry.get("command") == "sqlcg"
-    ):
-        console.print(
-            "[blue]Updating[/blue] MCP entry from [dim]uvx[/dim] to local "
-            "[green]sqlcg[/green] binary (faster startup). Writing…"
-        )
-
-    mcp_servers[_SERVER_KEY] = entry
-
-    if dry_run is True:
-        console.print("[dim]--dry-run: would write:[/dim]")
-        console.print_json(json.dumps(settings, indent=2))
-        _provision_skill(resolved_scope, repo, dry_run)
-        return
+    data.setdefault("mcpServers", {}).setdefault("user", {})[_SERVER_KEY] = entry
 
     try:
-        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)
+        tmp = claude_json.with_suffix(".tmp")
+        tmp.write_text(json.dumps(data, indent=2) + "\n")
+        os.replace(tmp, claude_json)
     except (OSError, TypeError, AttributeError):
         pass  # Ignore file I/O errors in testing
 
-    cmd_str = f"{entry['command']} {' '.join(entry['args'])}"
+    cmd_str = " ".join(cmd_parts)
     console.print(f"[green]Configured:[/green] {_SERVER_KEY} → {cmd_str}")
-    console.print(f"[dim]Written to {settings_path}[/dim]")
+    console.print(f"[dim]Written to {claude_json}[/dim]")
 
-    # Note about cold cache if uvx was chosen
     if entry.get("command") == "uvx":
         console.print(
             "[yellow]Note:[/yellow] First startup downloads dependencies (~30s). "
@@ -108,9 +134,20 @@ def install_cmd(
         )
 
     console.print("\nRestart Claude Code to pick up the new MCP server.")
+    _provision_skill(resolved_scope, repo, dry_run=False)
+
 
-    # Provision the skill file
-    _provision_skill(resolved_scope, repo, dry_run)
+def _preview_claude_json(claude_json: Path, entry: dict) -> None:
+    """Print what would be written to ~/.claude.json without touching the file."""
+    if claude_json.exists():
+        try:
+            data: dict = json.loads(claude_json.read_text())
+        except (json.JSONDecodeError, OSError, TypeError):
+            data = {}
+    else:
+        data = {}
+    data.setdefault("mcpServers", {}).setdefault("user", {})[_SERVER_KEY] = entry
+    console.print_json(json.dumps(data, indent=2))
 
 
 def _resolve_scope(scope: str | None) -> str:

sqlcg/cli/commands/mcp.py

@@ -22,28 +22,34 @@ def _server_entry() -> dict:
 
 @app.command("setup")
 def mcp_setup(print_only: bool = typer.Option(True, "--print/--write")) -> None:
-    """Print or write MCP server config JSON."""
+    """Print or write MCP server config JSON.
+
+    --print (default): print the JSON snippet for manual insertion.
+    --write: write to ~/.claude.json under mcpServers.user (the correct path
+             for Claude Code — not settings.json, which Claude Code does not read
+             for MCP servers).
+    """
     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():
+    # Write to ~/.claude.json (correct path for Claude Code MCP servers)
+    claude_json = Path.home() / ".claude.json"
+    if claude_json.exists():
         try:
-            settings: dict = json.loads(config_path.read_text())
+            data: dict = json.loads(claude_json.read_text())
         except json.JSONDecodeError:
-            settings = {}
+            data = {}
     else:
-        settings = {}
+        data = {}
 
-    settings.setdefault("mcpServers", {})[_SERVER_KEY] = entry
+    data.setdefault("mcpServers", {}).setdefault("user", {})[_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}")
+    tmp = claude_json.with_suffix(".tmp")
+    tmp.write_text(json.dumps(data, indent=2) + "\n")
+    os.replace(tmp, claude_json)
+    console.print(f"[green]Configuration written to[/green] {claude_json}")
     console.print("Note: Binary is `sqlcg`; PyPI package is `sql-code-graph`.")
 
 

sqlcg/cli/commands/reindex.py

@@ -60,6 +60,9 @@ def reindex_cmd(  # noqa: B008
     from sqlcg.core.schema import SCHEMA_VERSION
     from sqlcg.indexer.indexer import Indexer
 
+    # Resolve to absolute path so ignore-spec and git delta receive an absolute root
+    path = path.resolve()
+
     # Resolve dialect
     if dialect == "auto":
         dialect = get_dialect(path)

sqlcg/core/config.py

@@ -19,6 +19,10 @@ class KuzuConfig(BaseModel):
         default=0,
         description="KuzuDB buffer pool size in MB (0 = use KuzuDB default)",
     )
+    log_path: Path = Field(
+        default_factory=lambda: Path.home() / ".sqlcg" / "index.log",
+        description="Path for parse-warning log file written during indexing",
+    )
 
     @classmethod
     def from_env(cls) -> "KuzuConfig":
@@ -29,9 +33,11 @@ class KuzuConfig(BaseModel):
         """
         env_path = os.getenv("SQLCG_DB_PATH")
         env_buf = os.getenv("SQLCG_BUFFER_POOL_MB")
+        env_log = os.getenv("SQLCG_LOG_PATH")
         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,
+            log_path=Path(env_log) if env_log else Path.home() / ".sqlcg" / "index.log",
         )
 
 
@@ -138,6 +144,7 @@ def get_noise_filter_patterns(path: Path) -> list[str]:
     """
     default_patterns = [
         "*_bck",
+        "*_bck_*",  # catches mid-suffix variants e.g. foo_bck_us39553, bar_bck_archive
         "*_bck_us",
         "*_bck_[0-9]*",
         "*_backup",

sqlcg/indexer/error_classify.py

@@ -93,10 +93,14 @@ def _classify_error(msg: str) -> str:
     if not msg:
         return "other"
 
-    # Timeout errors
+    # Timeout errors (including pool-path poison retries)
     if msg.startswith("timeout:"):
         return "timeout"
 
+    # Poison-retry: file repeatedly timed out in pool worker; treat as timeout bucket
+    if msg.startswith("skipped:poison"):
+        return "timeout"
+
     # Skip markers
     if msg.startswith("col_lineage_skip:"):
         if "pure_ddl_file" in msg: