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

{sql_code_graph-1.0.1.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.1
+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.1.dist-info → sql_code_graph-1.0.2.dist-info}/RECORD

@@ -1,22 +1,22 @@
-sqlcg/__init__.py,sha256=rhzbVCLAOlBWTlliY-J8bh3jG3Hn7-5PPLDJwujXW_g,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=b6ns4_1ZVnHE5GeIb2N8YogjUvhjkzn_F9HrwCqrt_Y,8253
-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/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=n8u_z2IjW-rX1m0wlJ9-N-jxQby_Y4J9blMEPYaf19Q,18360
+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=nkhl2jVBFRPKHtr2PKfYy6vTdW64v7KKUnfMwVG2ZMU,43941
+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.1.dist-info/METADATA,sha256=vFhNG1uWAym_RQ21vDWG0tlogTOe2DDjCmrJp8X1txg,12806
-sql_code_graph-1.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sql_code_graph-1.0.1.dist-info/entry_points.txt,sha256=Wfe49sVzV9p4eVFGo5RxcV-frr3HOP0yzzst8JBxQLQ,46
-sql_code_graph-1.0.1.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.1"
+__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)
@@ -100,6 +132,16 @@ def index_cmd(  # noqa: B008
         # 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(

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:

sqlcg/indexer/git_delta.py

@@ -51,6 +51,7 @@ def git_name_status_delta(root: Path, old_sha: str, new_sha: str) -> Delta | Non
         unknown SHA, shallow clone, or git not available).  Callers MUST fall
         back to a full index_repo when None is returned.
     """
+    root = root.resolve()  # guard: caller may pass a relative path (e.g. Path("."))
     try:
         result = subprocess.run(
             ["git", "diff", "--name-status", old_sha, new_sha],

sqlcg/indexer/pool.py

@@ -285,7 +285,9 @@ class HardKillPool:
                 tidx = queue.pop(0)
                 path = tasks[tidx].get("path", "")
                 if kill_counts.get(path, 0) >= poison_retries:
-                    results[tidx] = _timeout_file(path, self._dialect, poison=True)
+                    results[tidx] = _timeout_file(
+                        path, self._dialect, timeout_s=per_task_timeout, poison=True
+                    )
                     logger.warning("Skipping %s — poisoned after %d kills", path, poison_retries)
                     if on_result is not None:
                         on_result()
@@ -375,7 +377,7 @@ class HardKillPool:
                     slot,
                     kill_counts[path],
                 )
-                results[tidx] = _timeout_file(path, self._dialect)
+                results[tidx] = _timeout_file(path, self._dialect, timeout_s=per_task_timeout)
                 if on_result is not None:
                     on_result()
                 self._respawn(w)
@@ -486,11 +488,14 @@ class HardKillPool:
 def _timeout_file(
     path: str,
     dialect: str | None,
+    timeout_s: float = 0.0,
     poison: bool = False,
 ) -> ParsedFile:
     pf = ParsedFile(path=Path(path), dialect=dialect)
-    msg = "skipped:poison" if poison else "timeout"
-    pf.errors.append(f"{msg} file={Path(path).name}")
+    if poison:
+        pf.errors.append(f"skipped:poison file={Path(path).name}")
+    else:
+        pf.errors.append(f"timeout:{timeout_s:.0f}s file={Path(path).name}")
     return pf
 
 

sqlcg/parsers/base.py

@@ -688,8 +688,126 @@ class SqlParser(ABC):
                     except Exception:
                         body_scope = None
 
-            # Extract output columns
-            for col_expr in col_expressions:
+            # INSERT positional column-list mapping (#25 fix).
+            # Compute the positional_col_names skip-set BEFORE the main column loop
+            # so the main loop can skip positions already handled here.
+            #
+            # When an INSERT has an explicit column list (INSERT INTO t (c1, c2) SELECT ...),
+            # the target column name at position idx is authoritative — the SELECT alias is
+            # cosmetic for the SELECT and meaningless to the INSERT target. This block
+            # overrides alias attribution for ALL positions (aliased or not).
+            #
+            # Guards applied here mirror the main column loop to preserve skip markers:
+            #   - Star expressions → emit col_lineage_skip:star, register pos, skip sg_lineage
+            #   - Pure-literal (no Column descendant) → register pos, skip sg_lineage (silent)
+            #   - Unaliased non-Column (func/arith/CASE) → emit col_lineage_skip:func_fallback,
+            #     register pos, skip sg_lineage
+            #   - Plain Column / aliased expression → call sg_lineage (the #25 happy path)
+            #
+            # CLAUDE.md invariant: body_no_with = body.copy() + strip-WITH happens ONCE
+            # before the inner loop; only the single projection is swapped per column.
+            positional_col_names: dict[int, str] = {}  # idx → insert_col_name
+            if isinstance(stmt, exp.Insert) and isinstance(stmt.this, exp.Schema):
+                insert_cols_list = [c.name for c in stmt.this.expressions]
+                # Build the WITH-stripped body ONCE here, before any per-column loop.
+                # Only the single projection is swapped per column below.
+                body_no_with = body.copy()
+                body_no_with.set("with_", None)
+                for _ins_idx, _col_expr in enumerate(col_expressions):
+                    if _ins_idx >= len(insert_cols_list):
+                        break
+                    _insert_col = insert_cols_list[_ins_idx]
+                    if not _insert_col:
+                        continue
+                    # Register position first so the main loop always skips it,
+                    # regardless of which guard fires below.
+                    positional_col_names[_ins_idx] = _insert_col
+
+                    # Guard 1: Star projection — emit skip marker (same as main loop).
+                    _inner_for_guard = (
+                        _col_expr.this if isinstance(_col_expr, exp.Alias) else _col_expr
+                    )
+                    if isinstance(_inner_for_guard, exp.Star) or (
+                        isinstance(_inner_for_guard, exp.Column)
+                        and isinstance(_inner_for_guard.this, exp.Star)
+                    ):
+                        _qualifier = (
+                            _inner_for_guard.table
+                            if isinstance(_inner_for_guard, exp.Column)
+                            else None
+                        )
+                        out.errors.append(f"col_lineage_skip:star:{_qualifier or '<unqualified>'}")
+                        continue  # no sg_lineage for star
+
+                    # Guard 2: Pure-literal — no Column descendants, nothing to trace.
+                    if not list(_col_expr.find_all(exp.Column)):
+                        continue  # silent skip, no sg_lineage
+
+                    # NOTE: do NOT emit func_fallback here for unaliased non-Column
+                    # expressions (functions, arithmetic, CASE …). The main loop emits
+                    # func_fallback for such expressions because a plain SELECT/CREATE VIEW
+                    # gives them no output column name. The positional INSERT column list
+                    # DOES supply that name (_insert_col): below we wrap the expression as
+                    # Alias(expr, _insert_col) and let sg_lineage trace through it — exactly
+                    # as the aliased form (e.g. `DATE(col) AS a`) already resolves. Guard 2
+                    # (above) already dropped genuinely-untraceable pure-literal expressions
+                    # (no Column descendant). Skipping column-containing expressions here would
+                    # make the #25 positional feature do its work and then discard the result,
+                    # dropping real lineage edges (regressed by eb19f29; broke COALESCE).
+
+                    # Positional mapping always wins — replace (or add) the alias with the
+                    # INSERT target column name regardless of SELECT alias.
+                    if _col_expr.alias and _col_expr.alias != _insert_col:
+                        self._log.debug(
+                            "INSERT positional override: SELECT alias %r → INSERT col %r"
+                            " at position %d",
+                            _col_expr.alias,
+                            _insert_col,
+                            _ins_idx,
+                        )
+                    # If the expression is already an Alias(inner, old_alias), unwrap it
+                    # before re-wrapping — otherwise we produce Alias(Alias(inner, x), c1)
+                    # which serialises as "inner AS x AS c1" (syntax error).
+                    _inner = _col_expr.this if isinstance(_col_expr, exp.Alias) else _col_expr
+                    _aliased = exp.Alias(this=_inner.copy(), alias=_insert_col)
+                    body_no_with.set("expressions", [_aliased])
+                    _patched_sql = body_no_with.sql(dialect=self.DIALECT)
+                    # Pass sources= (not scope=) here: the patched SQL is a freshly
+                    # serialised string — the scope was built from the original body AST
+                    # and does not correspond to this new string.
+                    #
+                    # Use `sources` (the cross-statement temp/CTAS map), NOT
+                    # `combined_sources`. combined_sources additionally carries the
+                    # SAME-STATEMENT CTE bodies (added above). Since body_no_with strips
+                    # the WITH clause from the patched SQL, those CTE names become opaque
+                    # source relations — passing their bodies as sources= would expand them
+                    # away, collapsing intermediate CTE→target hops into the deepest source
+                    # (regressed by eb19f29; broke the MA_AANTAL_OP_ORDER anchor link 5).
+                    # Cross-statement temps (e.g. CREATE TEMP TABLE t) live in `sources`
+                    # and SHOULD still expand (E36 multi-temp: t → src).
+                    try:
+                        _root = sg_lineage(
+                            _insert_col,
+                            _patched_sql,
+                            dialect=self.DIALECT,
+                            sources=sources or {},
+                        )
+                        if _root:
+                            _new_edges = self._lineage_node_to_edges(
+                                _root,
+                                dst_col_name=_insert_col,
+                                dst_table=dst_table,
+                                path=path,
+                                out=out,
+                            )
+                            edges.extend(_new_edges)
+                    except Exception:
+                        pass
+
+            # Extract output columns — skip positions handled by the positional INSERT block
+            for loop_idx, col_expr in enumerate(col_expressions):
+                if loop_idx in positional_col_names:
+                    continue  # positional INSERT block already emitted this column
                 # Skip star projections — sg_lineage requires a concrete column name.
                 if isinstance(col_expr, exp.Star) or (
                     isinstance(col_expr, exp.Column) and isinstance(col_expr.this, exp.Star)
@@ -919,47 +1037,6 @@ class SqlParser(ABC):
                                         cte_col_name,
                                     )
 
-            # INSERT column-list aliasing (T-07-02 link 5).
-            # When an INSERT has an explicit column list and the SELECT expression has
-            # no alias (e.g. SELECT SUM(x) FROM cte), the INSERT column at the same
-            # position provides the destination col name. Stripping the WITH clause
-            # stops sg_lineage at the CTE name boundary (doesn't expand into bodies).
-            if isinstance(stmt, exp.Insert) and isinstance(stmt.this, exp.Schema):
-                insert_cols = [c.name for c in stmt.this.expressions]
-                # Build the WITH-stripped body ONCE before the loop and only swap its
-                # single projection per column (regressed in 4234e5d, which moved the
-                # full-body body.copy() inside the loop → O(N_cols) full-body deepcopies
-                # for wide INSERT ... SELECT). Stripping WITH stops sg_lineage at the CTE
-                # name boundary.
-                body_no_with = body.copy()
-                body_no_with.set("with_", None)
-                for idx, col_expr in enumerate(col_expressions):
-                    if idx >= len(insert_cols):
-                        break
-                    if col_expr.alias:
-                        continue  # already handled by the main col loop
-                    insert_col = insert_cols[idx]
-                    if not insert_col:
-                        continue
-                    # Patch the shared body with this column's aliased expression so
-                    # sg_lineage can trace it to the INSERT column name.
-                    aliased = exp.Alias(this=col_expr.copy(), alias=insert_col)
-                    body_no_with.set("expressions", [aliased])
-                    patched_sql = body_no_with.sql(dialect=self.DIALECT)
-                    try:
-                        root = sg_lineage(insert_col, patched_sql, dialect=self.DIALECT)
-                        if root:
-                            new_edges = self._lineage_node_to_edges(
-                                root,
-                                dst_col_name=insert_col,
-                                dst_table=dst_table,
-                                path=path,
-                                out=out,
-                            )
-                            edges.extend(new_edges)
-                    except Exception:
-                        pass
-
         except Exception as exc:
             self._log.debug(
                 "column lineage extraction failed for entire statement: file=%s error=%s",

sqlcg/server/server.py

@@ -1,35 +1,76 @@
 """MCP server for SQL Code Graph.
 
 Exposes FastMCP tools for lineage queries, pattern search, and indexing.
-MCP protocol uses stdout for message transport, so this module redirects
-stdout to stderr to prevent user logs from corrupting the protocol stream.
+MCP protocol uses stdout (fd 1) for JSON-RPC message transport. This module
+captures fd 1 as a raw binary buffer BEFORE any logging redirection so that
+the captured buffer can be passed explicitly to stdio_server(). This ensures
+JSON-RPC frames always go to fd 1 regardless of what sys.stdout points to
+at call time.
+
+Ordering invariant (must not change):
+  1. os.dup(1) → _real_stdout_buffer        (first — before everything)
+  2. from mcp.server import FastMCP          (module-level import)
+  3. mcp = FastMCP("SQL Code Graph")         (module-level; tools.py registers here)
+  4. main() calls _configure_mcp_logging()   (not at module scope)
 """
 
+import os
 import sys
 
-from dotenv import load_dotenv
-from mcp.server import FastMCP
+# Capture the real fd 1 binary stream FIRST — before _configure_mcp_logging()
+# (which replaces sys.stdout) AND before FastMCP("SQL Code Graph") construction.
+# stdio_server() receives this explicitly so JSON-RPC frames go to fd 1
+# regardless of what sys.stdout points to afterward.
+# Guards against the v1.0.0/v1.0.1 regression where frames went to fd 2.
+_real_stdout_buffer = os.fdopen(os.dup(1), "wb", buffering=0)
 
-from sqlcg.utils.logging import getLogger
+from dotenv import load_dotenv  # noqa: E402
+from mcp.server import FastMCP  # noqa: E402
+
+from sqlcg.utils.logging import getLogger  # noqa: E402
 
 logger = getLogger(__name__)
 
+# Create FastMCP instance at module scope so tools.py can import and register with it.
+# This is safe because _real_stdout_buffer has already captured fd 1 above.
+mcp = FastMCP("SQL Code Graph")
+
 
 def _configure_mcp_logging() -> None:
-    """Redirect sys.stdout to sys.stderr to protect MCP protocol.
+    """Redirect sys.stdout to sys.stderr and configure logging to stderr.
 
-    MCP uses stdout for JSON-RPC messages. Any user print() or log output
-    to stdout would corrupt the protocol. This function must be called before
-    mcp.run() and before any code that might print to stdout.
+    sys.stdout is replaced with sys.stderr so that any stray print() call
+    does not pollute fd 1 (reserved for MCP JSON-RPC frames).
+    The real fd 1 binary stream is captured in _real_stdout_buffer at module
+    top before this replacement and passed explicitly to stdio_server().
+
+    Must be called inside main(), not at module scope, so that
+    _real_stdout_buffer captures fd 1 before the redirect.
     """
+    import logging
+
     sys.stdout = sys.stderr
+    logging.basicConfig(stream=sys.stderr, level=logging.WARNING)
 
 
-# Protect stdout before importing FastMCP (which may emit output during import)
-_configure_mcp_logging()
+async def _run_stdio_async_with_real_stdout() -> None:
+    """Run the MCP server loop with JSON-RPC frames explicitly on fd 1.
 
-# Create FastMCP instance at module scope so tools.py can import and register with it
-mcp = FastMCP("SQL Code Graph")
+    Bypasses FastMCP.run_stdio_async() (which uses sys.stdout at call time)
+    and drives the server loop directly with the captured _real_stdout_buffer.
+    """
+    from io import TextIOWrapper
+
+    import anyio
+    from mcp.server.stdio import stdio_server
+
+    stdout_text = TextIOWrapper(_real_stdout_buffer, encoding="utf-8", line_buffering=False)
+    async with stdio_server(stdout=anyio.wrap_file(stdout_text)) as (read_stream, write_stream):
+        await mcp._mcp_server.run(
+            read_stream,
+            write_stream,
+            mcp._mcp_server.create_initialization_options(),
+        )
 
 
 def main(db_path: str | None = None) -> None:
@@ -38,10 +79,13 @@ def main(db_path: str | None = None) -> None:
     Args:
         db_path: Path to KùzuDB database. If None, uses SQLCG_DB_PATH env var
                 or ~/.sqlcg/graph.db (via get_db_path in tools module).
-
-    Raises:
-        RuntimeError: If tools fail to initialize or FastMCP server fails.
     """
+    import anyio
+
+    # Must be first — redirects sys.stdout → sys.stderr so stray prints don't
+    # corrupt fd 1. _real_stdout_buffer was already captured at module top.
+    _configure_mcp_logging()
+
     load_dotenv()
 
     # Import tools module to trigger tool registration via @mcp.tool() decorators
@@ -50,8 +94,7 @@ def main(db_path: str | None = None) -> None:
     # Initialize the backend singleton used by all tools
     sqlcg.server.tools.init_backend(db_path)
 
-    # Run the MCP server event loop, ensuring backend is closed on shutdown
     try:
-        mcp.run()
+        anyio.run(_run_stdio_async_with_real_stdout)
     finally:
         sqlcg.server.tools.shutdown_backend()

sqlcg/server/tools.py

@@ -183,6 +183,19 @@ def _assert_indexed(db: GraphBackend) -> None:
         )
 
 
+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 _parse_column_ref(col_ref: str) -> tuple[str, str]:
     """Parse column reference "table.column" or "catalog.db.table.column".
 
@@ -554,9 +567,54 @@ def trace_column_lineage(table_col: str, max_depth: int | None = None) -> Lineag
 
         mermaid = _build_mermaid(col_id, edges) if edges else None
 
+        # Bare-name fallback: when the primary query returns empty and the ref has a
+        # schema component (3+ parts), retry with the schema prefix stripped.
+        # This handles unqualified INSERT targets indexed without a schema prefix.
+        bare_fallback_used = False
+        if not lineage and len(table_col.split(".")) >= 3:
+            bare = _bare_ref(table_col)
+            bare_queue: deque[tuple[str, int]] = deque([(bare, 0)])
+            bare_visited: set[str] = set()
+            bare_emitted: set[str] = set()
+            while bare_queue:
+                current_id, depth = bare_queue.popleft()
+                if current_id in bare_visited or (max_depth is not None and depth > max_depth):
+                    continue
+                if len(bare_visited) >= max_nodes:
+                    break
+                bare_visited.add(current_id)
+                rows = db.run_read(TRACE_COLUMN_LINEAGE_QUERY, {"id": current_id})
+                for row in rows:
+                    node_id = row["id"]
+                    edges.append((node_id, current_id, row.get("transform") or "SELECT"))
+                    if node_id not in bare_visited and node_id not in bare_emitted:
+                        bare_emitted.add(node_id)
+                        lineage.append(
+                            LineageNode(
+                                name=row.get("col_name", ""),
+                                kind="column",
+                                table=row.get("table_qualified"),
+                                file=None,
+                                confidence=row.get("confidence"),
+                            )
+                        )
+                    if node_id not in bare_visited:
+                        bare_queue.append((node_id, depth + 1))
+            if lineage:
+                bare_fallback_used = True
+                mermaid = _build_mermaid(bare, edges) if edges else None
+
         # Populate hint if result is empty (Step 4.1)
         hint = None
-        if not lineage:
+        if bare_fallback_used:
+            bare = _bare_ref(table_col)
+            hint = (
+                f"No results for '{table_col}'. Found lineage 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."
+            )
+        elif not lineage:
             hint = (
                 "No lineage found. Ensure the column reference includes the schema prefix "
                 "(e.g., ba.table_name.column_name). Check that 'sqlcg db info' shows "

sqlcg/utils/ignore.py

@@ -14,6 +14,7 @@ def load_ignore_spec(root: Path) -> pathspec.PathSpec:
     Returns:
         PathSpec object for matching ignore patterns
     """
+    root = Path(root).resolve()  # guard: caller may pass a relative path (e.g. Path("."))
     ignore_file = root / ".sqlcgignore"
     if ignore_file.exists():
         patterns = ignore_file.read_text().splitlines()
@@ -33,4 +34,5 @@ def is_ignored(path: Path, root: Path, spec: pathspec.PathSpec) -> bool:
     Returns:
         True if the path matches any ignore pattern
     """
+    root = Path(root).resolve()  # guard: ensure root is absolute before relative_to()
     return spec.match_file(str(path.relative_to(root)))