sql-code-graph 1.5.0__py3-none-any.whl → 1.33.0__py3-none-any.whl

{sql_code_graph-1.5.0.dist-info → sql_code_graph-1.33.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-code-graph
-Version: 1.5.0
+Version: 1.33.0
 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
@@ -36,7 +36,7 @@ Description-Content-Type: text/markdown
 
 # sql-code-graph
 
-> **Pre-1.0 — expect breaking changes.** APIs, CLI flags, and graph schema may
+> **No backward-compatibility guarantees.** APIs, CLI flags, and graph schema may
 > change between releases without a deprecation period. Pin to an exact version
 > in production. Re-indexing is always the migration path.
 
@@ -90,10 +90,13 @@ for that project.
 ## Full setup (recommended)
 
 ```bash
-# 1. Install
-pip install sql-code-graph
+# 1. Install (this project uses uv — never pip)
+uv tool install sql-code-graph          # global tool (recommended)
+# — or, from a source checkout:
+#   git clone https://github.com/Warhorze/sql-code-graph
+#   cd sql-code-graph && uv sync        # then run via `uv run sqlcg …`
 
-# 2. Register with Claude Code (~/.claude/settings.json)
+# 2. Register with Claude Code (writes ~/.claude.json)
 sqlcg install
 
 # 3. Restart Claude Code
@@ -138,7 +141,7 @@ This project uses sql-code-graph. MCP tools are available:
 - `trace_column_lineage` — trace where a column's value comes from
 - `get_upstream_dependencies` / `get_downstream_dependencies` — dependency chains
 - `search_sql_pattern` — full-text search across all indexed SQL
-- `execute_cypher` — raw graph query for advanced analysis
+- `execute_sql` — raw read-only SQL query for advanced analysis
 ```
 
 The MCP server works without this — Claude can discover the tools on its own —
@@ -193,10 +196,51 @@ sqlcg index . --dialect snowflake   # index DDL + ETLs together
 After indexing, `sqlcg db info` shows non-zero `STAR_EXPANSION lineage edges`, and
 `trace_column_lineage` returns results for queries that previously returned empty.
 
-> **Note:** earlier versions accepted an exported `INFORMATION_SCHEMA` CSV (`sqlcg
-> load-schema`). That path was **removed** — profiling showed it added zero lineage
-> edges over DDL + cross-file CTAS resolution on a real warehouse. DDL is now the
-> single source of column truth; no CSV is needed or accepted.
+> **Note:** an earlier `sqlcg load-schema` command was removed in 2026-05 — it fed
+> column names into the parse/qualify loop (hot path) and measured zero edge delta on
+> a real warehouse.  The new `sqlcg catalog load` (see below) is different: it writes
+> `HAS_COLUMN` rows **after** indexing and never touches the parser.
+
+## INFORMATION_SCHEMA catalog enrichment
+
+If your warehouse DDL lives in XML changelogs (Liquibase, Flyway) or other non-SQL
+formats that sqlcg cannot parse, you can supply an `INFORMATION_SCHEMA.COLUMNS` export
+to enrich edge health without re-parsing anything.
+
+```bash
+# Export from Snowflake (or any SQL client):
+# SELECT table_catalog, table_schema, table_name, column_name, ordinal_position, data_type
+# FROM information_schema.columns
+# WHERE table_schema NOT IN ('INFORMATION_SCHEMA')
+# ORDER BY table_schema, table_name, ordinal_position;
+# → save as columns.csv
+
+sqlcg catalog load columns.csv
+sqlcg gain          # check the delta
+```
+
+**What it does:**
+- Reads `table_catalog` (optional), `table_schema`, `table_name`, `column_name` columns.
+- Delimiter sniffed (`,` or `;`); extra columns ignored; names case-folded to lowercase.
+- Creates `SqlColumn` nodes and `HAS_COLUMN(source='information_schema')` edges.
+- DDL-sourced rows are never overwritten (`ddl > information_schema > usage` precedence).
+- Idempotent — running it twice produces no row growth.
+- Catalog-sourced rows survive per-file reindex (`sqlcg reindex`).
+
+**Persisting across full rebuilds:** add to `.sqlcg.toml`:
+
+```toml
+[sqlcg.catalog]
+path = "/path/to/columns.csv"
+```
+
+With this set, `sqlcg index` automatically re-applies the catalog at the end of each
+full rebuild. If the file is missing, indexing succeeds with a warning.
+
+**What it does not do:**
+- It does not feed column names into the parse/qualify hot path — `SELECT *` expansion
+  uses only DDL files and cross-file CTAS bodies (unchanged).
+- It does not create new lineage edges — it only validates / invalidates existing ones.
 
 ## MCP tools reference
 
@@ -207,18 +251,23 @@ After indexing, `sqlcg db info` shows non-zero `STAR_EXPANSION lineage edges`, a
 | `trace_column_lineage(table_col)` | Trace a column's value upstream to its sources |
 | `get_upstream_dependencies(table_col)` | Full upstream dependency chain |
 | `get_downstream_dependencies(table_col)` | Full downstream dependency chain |
-| `find_table_usages(table_name)` | Find all queries that read a table |
+| `find_table_usages(table_name)` | Find all queries that read a table (3-signal: direct SELECT, SELECT *, or column-lineage CTE read) |
 | `find_definition(table_qualified)` | Find where a table/view is defined |
 | **Change impact** | |
-| `get_change_scope(table_qualified)` | Blast radius of changing a table (impact + risk) |
-| `diff_impact(changed_files)` | What a set of changed files affects downstream |
+| `get_change_scope(table_qualified)` | Blast radius of changing a table (impact + risk); `gating_join_tables` field adds row-reachability supplement (see caveats) |
+| `diff_impact(changed_files)` | What a set of changed files affects downstream; `gating_join_tables` field adds row-reachability supplement (see caveats) |
 | `get_backfill_order(table_qualified)` | Topological rebuild/backfill order |
 | `scope_change(target)` | Synthesised change-scope summary for a target |
+| `get_empty_propagation(tables)` | Downstream blast radius when named table(s) are empty — two views: value-derivation (primary) + row-reachability (supplement) |
+| `get_pr_impact(base_ref)` | Detect producers a PR dropped + their blast radius; code-regression detection, not runtime monitoring |
+| **Analysis** | |
+| `get_hub_ranking(k)` | Top-k tables by downstream dependent count (hub/centrality) |
+| `analyze_unused()` | Tables with no within-corpus consumers (dead-code candidates, heuristic); uses 3-signal "used" definition — direct SELECT, SELECT *, or CTE-derived column read |
 | **Search & meta** | |
 | `search_sql_pattern(query)` | Full-text search across indexed SQL |
 | `list_dialects_and_repos()` | List indexed repos and dialects (catalogue) |
 | `db_info()` | Graph health, node counts, parse quality breakdown, warnings, freshness (indexed SHA vs HEAD) |
-| `execute_cypher(query)` | Raw Cypher query against the graph |
+| `execute_sql(query)` | Raw read-only SQL query against the graph |
 | `submit_feedback(...)` | Report a false positive/negative to improve metrics |
 
 > **Input format**: lineage/dependency tools expect a **schema-qualified** column
@@ -249,7 +298,9 @@ sqlcg index <path> --dialect auto      # read dialect from .sqlcg.toml
 sqlcg index <path> --profile           # index + print per-stage timing and slowest files
 sqlcg index <path> --include-working-tree  # also index uncommitted changes (marks graph dirty)
 sqlcg reindex <path> --from <sha> --to <sha>  # incremental resync of only changed files
-sqlcg analyze unused                   # tables with no query references
+sqlcg analyze unused                   # tables with no within-corpus consumers (3-signal: direct SELECT, SELECT *, or CTE-derived column read)
+sqlcg analyze empty-impact <table>...  # downstream blast radius when named table(s) are empty (two views)
+sqlcg analyze pr-impact --base <ref>   # detect producers a PR dropped + their blast radius (code-regression detection)
 sqlcg analyze upstream/downstream      # trace lineage from the CLI
 sqlcg find table/column/pattern        # search the graph
 sqlcg watch <path>                     # watch for file changes
@@ -259,16 +310,26 @@ sqlcg gain                             # show usage metrics
 sqlcg report                           # generate FP/error report
 sqlcg mcp best-practices               # print the fact/heuristic boundary for the MCP tools
 sqlcg mcp start                        # start MCP server manually
-sqlcg mcp status                       # server status JSON (via control socket)
+sqlcg mcp status                       # server status JSON — incl. running version + stale_by_version
 sqlcg mcp stop                         # stop the running MCP server gracefully
 sqlcg mcp restart                      # stop the server (client must respawn it)
 sqlcg version                          # show installed version
 ```
 
+### Staying on the latest build (v1.5.0)
+
+The installed package, the CLI, and the running MCP server all report the **same**
+version (`sqlcg.__version__`). After upgrading, an editor may still be talking to an
+old MCP process — `sqlcg mcp status` surfaces this directly: it reports the running
+server's `version` and a `stale_by_version` flag that is `true` when the live server
+differs from the installed build. Re-running `sqlcg install` stops the stale server so
+your editor respawns it on the new build, so you never debug against an outdated server.
+
 ### Reads while the server is running (v1.2.0)
 
-KuzuDB allows a single writer, so while the MCP server is live it holds the
-database lock. CLI **read** commands (`find`, `analyze`, `db info`, `list-repos`,
+DuckDB takes an exclusive lock on the database file, so while the MCP server is
+live it holds that lock (other processes cannot open the file, even read-only).
+CLI **read** commands (`find`, `analyze`, `db info`, `list-repos`,
 `gain`) automatically route their query through the running server over its
 control socket and return rows as usual — no flag, no config. When no server is
 running they open the database directly, exactly as before. If the server is

sql_code_graph-1.33.0.dist-info/RECORD

@@ -0,0 +1,71 @@
+sqlcg/__init__.py,sha256=eUMoB2vKl2ho6_w-fT0h0Atb36ONmYWYv3oayOjVeIs,116
+sqlcg/__main__.py,sha256=1YoFLcqEgTwYq1J3TbUwpkdG0zeeLIf2fJvwWI-CLFU,109
+sqlcg/cli/__init__.py,sha256=W8fD0LpMq2xm_5WKGNMvJh2WBL1ho5E8hUeAqXQYT1g,28
+sqlcg/cli/coverage.py,sha256=Xm9ITzZDHv2mJ70Q5jCacVuhDStVrE3gq12_-Ypvtd8,43823
+sqlcg/cli/main.py,sha256=tlFvl-l9hWfZBP9dO2svZXvLDbh7T5731CFyctuVqDI,2485
+sqlcg/cli/commands/__init__.py,sha256=oSHtr6VD-jNubOjuCQyZj2tBppjMEpQDh-IGQ8of9eA,30
+sqlcg/cli/commands/analyze.py,sha256=XMax3uHyNEe8SIMEhiLBdtbQb8QUwncoQKTB2LIT3Vg,30000
+sqlcg/cli/commands/catalog.py,sha256=xCIWp_9xcDPHIMUB0xrZR3-G0WMvKbfq4yMwe2sDT2g,12670
+sqlcg/cli/commands/db.py,sha256=QEDPs0boeFe8ETE8BWe7I2JLSXROUI571SHXMTUqxh8,7982
+sqlcg/cli/commands/find.py,sha256=uMdG08bU-AvB9RqsTKPfdVnJet7b3Ebj0xbsjqTclYA,2678
+sqlcg/cli/commands/gain.py,sha256=PQCWjlisjUY4Gz_MkppXPI1_w8xsB4DPlN7uAxx0GvY,10149
+sqlcg/cli/commands/git.py,sha256=OCqq5ApKgOyYouC_olJoyugaS2jsvEkq5MEcmFAXXEo,7255
+sqlcg/cli/commands/index.py,sha256=KGy0vPlvFcMetBjT5wIEvEcy9MEcLt7lhNaKfRWUkgU,19502
+sqlcg/cli/commands/install.py,sha256=4aZzvDNdl2Ea5v-ufR8Oj1qq30oGS_9jX17etYpoan8,10148
+sqlcg/cli/commands/mcp.py,sha256=drh5udcroZFddmJAG3q9JWxekDqTO9H4xC-oIqiis-Y,14871
+sqlcg/cli/commands/reindex.py,sha256=pNBonQYUhHwfJFWJjWq_uQorMmTcJ9HRT1MNH6v_YYo,19357
+sqlcg/cli/commands/report.py,sha256=JU0qjyMxwOukE7bN3XvvIzOI7zMg_Gsnvk_8F6pKNpA,4915
+sqlcg/cli/commands/uninstall.py,sha256=WrA1FnINxnd6mmE4-_QBK0aHBnibstJeAT8swnQKG4M,8962
+sqlcg/cli/commands/watch.py,sha256=_OvUQ4m_Pp2lAzI_f9UX2Gwb56zbsaSC4Tj8h51uciA,2806
+sqlcg/core/__init__.py,sha256=dXvLWpbQ72f5CM6sKSvBDnEGqGuIZaN5MmHyD8Vf1aA,154
+sqlcg/core/config.py,sha256=QxhIiF_let_ablMa-WttGbcAlCCDIpT4lR4tUVymIEI,19091
+sqlcg/core/duckdb_backend.py,sha256=Yc1TBYvR7Yc3jaz4cZ6VseFEhTemm9rBe4jAGK0Fx0s,40112
+sqlcg/core/freshness.py,sha256=Cm-w7jACPrt8TIstZpCzDJpYsHCiBo63ni5js8wCGbg,6248
+sqlcg/core/graph_db.py,sha256=QLkJk1bDA9s00QQlivBBfoUl6GSZiVSC6_9kY-IxsuY,10255
+sqlcg/core/jobs.py,sha256=Je-fCdSKRgiSsv1W8SgNAlp36a7t7-pJZ-qKPbka9OE,3298
+sqlcg/core/noise_match.py,sha256=8jxMBum0HB7wnVyS8hHaklO279QOSNKDmPtv-0RujD8,4781
+sqlcg/core/queries.cypher,sha256=cvPOVe5GUOzJN4bxUvDxNI--xIIP8gm42TR-gUnea4U,4685
+sqlcg/core/queries.py,sha256=LgJcxMfienHD-ug2tAKMfcpfFrhtJvVXCsxrco9jAb0,3513
+sqlcg/core/queries.sql,sha256=EDSnJKz6gnWWYTlXBmyGmNYNhuX5V11CTP9IWVs0YlU,13695
+sqlcg/core/schema.cypher,sha256=StaJqIzOLwF2X9HYvfHSdGiYGFb_YkiHubPrTu-Qpmg,2898
+sqlcg/core/schema.py,sha256=6KrMzbfceM4k0p2i7hPz8eNBco5_1eGXwdGTd3VUaok,1477
+sqlcg/indexer/__init__.py,sha256=Wh20Unz2OHs1oIyWLrpurPAasF0BET2g4iXtNk7mh2U,56
+sqlcg/indexer/dbt_adapter.py,sha256=EB5x1WU5Z9d-I97ADDj88S_hG1C4z4nbrv8JUCzXfy8,686
+sqlcg/indexer/error_classify.py,sha256=-sp8cRmuOBHu_CxnCtaXf34YxHFYwIFNjIrn4LaEv6M,7142
+sqlcg/indexer/git_delta.py,sha256=zYdH5q-jV7w_ne8Oxdywsy0N3rwUjpd5RjEDurlrMSA,5026
+sqlcg/indexer/indexer.py,sha256=qUTMkK3P3eCghjGzmM9QwzfUL23FOJ5siQ5HS_1l4nk,98037
+sqlcg/indexer/pool.py,sha256=iMmCQtpDRKBTQBep2_EUq9THcsE18Zgk0hdaFB_CwiA,19006
+sqlcg/indexer/walker.py,sha256=Cft6JiJtdBFy0HR6L9pJdr5Fg0eRR3XBW1OMtM2apto,1947
+sqlcg/indexer/watcher.py,sha256=mJQq1LASRLKKwhz0WhCUWPLLqyPR2_-FD_8efYU6gE8,8442
+sqlcg/lineage/__init__.py,sha256=Da1DlYwtK13WHv_RnHjAtNkHTOuFbhxqCjT1Le7DsWM,46
+sqlcg/lineage/aggregator.py,sha256=zR9h0I14GtPQYT9bTs_UbVyjaUVgpEhAynKBNc4VPnA,13325
+sqlcg/lineage/schema_resolver.py,sha256=iXt6LYF6UVWsGUpcfbmjmGn9wCgXl721lTGf_8AaWcc,7320
+sqlcg/metrics/__init__.py,sha256=hLJ6wm4St8qqYwKh3o9QG7lcEt1BEYM31ccqO9tGpIg,133
+sqlcg/metrics/store.py,sha256=KuDtxvyAgug9_KtiSCpvgKM2VZM7VSaI3D11uMLjJJk,10604
+sqlcg/parsers/__init__.py,sha256=AamA8wBbDZV9_zEtZCI4Hyen5UAVKHmBwjTghTt2PZE,785
+sqlcg/parsers/ansi_parser.py,sha256=KLbNapfPU20eWK-pullEFvhP78aroU9qlg2aj8ZcESo,37926
+sqlcg/parsers/base.py,sha256=D9FwirsitJEGoYNUvclWVbeMgvkePr4Frqbs3G29XEg,92871
+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
+sqlcg/parsers/snowflake_parser.py,sha256=cv7bzBm6Wmwa8uY41Y59ebfFjnP1Gk0Sjp2KN_QBGD8,47542
+sqlcg/parsers/tsql_parser.py,sha256=RRj1pACtAk2tLTDaFWRYF67a0IDvaf5A1YQXWIz0bpQ,956
+sqlcg/server/__init__.py,sha256=n4wuNE7xyJIJxJZBtmtdccCMQfvTdF-IqIaZVbC4FC4,35
+sqlcg/server/control.py,sha256=qUcztb_aDhL-_X_Nq4q6uGx17cUlbLnI6vUpoZsEjbo,4506
+sqlcg/server/exceptions.py,sha256=EONw34icOByCTpppSQrvQBW6asc4hfqaGDCAFjv96II,469
+sqlcg/server/models.py,sha256=vp9oG81V6cSkbkbH8HZ8ZrEGWzDLapgojQHhk9niC0c,29194
+sqlcg/server/noise_filter.py,sha256=gTuiRKVFAizf_F4MODY4T34IQgzoxiDb-ilaTgg7Voo,6171
+sqlcg/server/read_client.py,sha256=ReeDHCff1G-WQzCH3Ow_hAUSEULRGq1lBr2AIOqur5c,10467
+sqlcg/server/selfheal.py,sha256=eL6D81N4tz-Feuw1uh3VzrUkW5qfbhLuLtyMqIiib3A,8299
+sqlcg/server/server.py,sha256=GUo6vVR2z80zH3geCanm1Eg-B4miUXmv78oLVBD4dlA,37407
+sqlcg/server/skill.py,sha256=TMCSn3kBYS7GzGz3L50ZwvuBUCD4otS0FSsPGK8juWs,14434
+sqlcg/server/tools.py,sha256=PhOvHotGJnTlcRWy_w8IMpIrJ4DSNLhi1vRzQW27aSg,121092
+sqlcg/server/writer.py,sha256=wXaXoL0adyDqrYxmnWb8mWXOmUQJxtLcPImeDPyxVes,18284
+sqlcg/utils/__init__.py,sha256=--iqt5ThTXmT8Wz7da8hs3n0zDfYPl8P-z5OgRJ_77E,154
+sqlcg/utils/hashing.py,sha256=H25-sYfxHKb3_IERFnHyAIYNiXN470Oqo5sJT_D3YOA,438
+sqlcg/utils/ignore.py,sha256=6__DfiYgynI2b8nH52O2BzI1EZcZ_LRazhqEOJVGGcE,1955
+sqlcg/utils/logging.py,sha256=u0fCmYsLj9o81vawm3xZTHaw68GQYVm7JxG-gP81u8A,840
+sql_code_graph-1.33.0.dist-info/METADATA,sha256=zEAtNat6hBOJ-K6FUzyTtc_qrR9waQWGdV8d_1meoQo,17791
+sql_code_graph-1.33.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+sql_code_graph-1.33.0.dist-info/entry_points.txt,sha256=Wfe49sVzV9p4eVFGo5RxcV-frr3HOP0yzzst8JBxQLQ,46
+sql_code_graph-1.33.0.dist-info/RECORD,,

sqlcg/__init__.py

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