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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-code-graph
-Version: 0.3.0
+Version: 1.0.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
@@ -38,6 +38,19 @@ Description-Content-Type: text/markdown
 
 # sql-code-graph
 
+> **Pre-1.0 — expect breaking changes.** 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.
+
+> **Dialect support.** sqlcg is built on [sqlglot](https://github.com/tobymao/sqlglot),
+> so in theory it can work for any dialect sqlglot parses. In practice we've only
+> tested it against a production **Snowflake** warehouse (~1,400 SQL files) — and
+> getting that one dialect working properly was already challenging. Other dialects
+> (`bigquery`, `postgres`, `ansi`, `tsql`, `dbt`) may well work, but their lineage
+> hasn't been validated, so expect rough edges. We'd gladly collaborate to get
+> another dialect integrated — [open an issue](https://github.com/Warhorze/sql-code-graph/issues)
+> with a minimal, anonymised corpus we can test against.
+
 SQL lineage and dependency analysis as an MCP server for Claude Code.
 
 Indexes a directory of `.sql` files into a graph database and exposes lineage
@@ -91,7 +104,7 @@ sqlcg install
 # Only git-tracked files are indexed — build artefacts, node_modules,
 # and .venv are ignored automatically.
 sqlcg db init
-sqlcg index ./sql --dialect snowflake   # or: bigquery, postgres, ansi
+sqlcg index ./sql --dialect snowflake   # snowflake is the only tested dialect
 
 # 5. (Optional) Keep the graph fresh on branch switches
 cd /your/sql/repo
@@ -108,7 +121,7 @@ To avoid passing `--dialect` every time, create `.sqlcg.toml` in your repo root:
 
 ```toml
 [sqlcg]
-dialect = "snowflake"   # snowflake | bigquery | postgres | ansi
+dialect = "snowflake"   # the only tested dialect
 ```
 
 The git hook and `sqlcg index --dialect auto` both read this file.
@@ -149,7 +162,8 @@ Quality is shown per-file after `sqlcg index` and in `sqlcg gain` Section F.
 `list_dialects_and_repos()` warns when scripting fallback exceeds 20% of queries.
 
 **What causes TABLE_ONLY?** Mostly `SELECT *` — sqlglot can't trace column names through
-a wildcard. Alias those selects to get FULL coverage.
+a wildcard without knowing the source table's columns. See [Resolving SELECT *](#resolving-select-)
+below for how sqlcg expands wildcards automatically from your DDL and CTAS bodies.
 
 **What causes SCRIPTING_FALLBACK?** Snowflake `$$` procedure bodies or `BEGIN…END` scripting
 blocks. sqlglot parses the block as a raw `Command` node and extracts DML via tokenizer
@@ -157,19 +171,62 @@ fallback. Table edges are usually correct; column edges are not.
 
 Check `sqlcg db info` for the parsing mode distribution across all indexed queries.
 
+## Resolving SELECT *
+
+A `SELECT *` ETL produces `TABLE_ONLY` parse quality because sqlglot needs the source
+table's column list to expand the wildcard into individual columns. sqlcg resolves this
+**automatically, with no extra setup** — there is no CSV to export or command to run.
+
+Wildcards are expanded from two sources harvested while indexing:
+
+1. **DDL files** — `CREATE TABLE` / `CREATE VIEW` statements give sqlcg the column list
+   for any table they define.
+2. **Cross-file CTAS bodies** — a `CREATE TABLE … AS SELECT` (or CTE) in one file is used
+   to resolve `SELECT *` against that table in another file.
+
+So the only thing you need to do is **index the DDL alongside your ETLs** — point `sqlcg
+index` at a path that contains both (e.g. the repo root, or both `ddl/` and `etl/`). The
+more of your `CREATE` statements sqlcg can see, the more wildcards it resolves.
+
+```bash
+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.
+
 ## MCP tools reference
 
 | Tool | Description |
 |------|-------------|
 | `index_repo(repo_path, dialect)` | Index a directory of SQL files |
-| `trace_column_lineage(table_col)` | Trace column lineage upstream |
-| `find_table_usages(table_name)` | Find all queries that read a table |
+| **Lineage & dependencies** | |
+| `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_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_backfill_order(table_qualified)` | Topological rebuild/backfill order |
+| `scope_change(target)` | Synthesised change-scope summary for a target |
+| **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 |
 | `execute_cypher(query)` | Raw Cypher query against the graph |
+| `submit_feedback(...)` | Report a false positive/negative to improve metrics |
+
+> **Input format**: lineage/dependency tools expect a **schema-qualified** column
+> reference — `schema.table.column` (e.g. `ba.orders.customer_id`), not a bare
+> `table.column`. Each returned node carries both `name` (the bare column) and
+> `table` (the owning `schema.table`), so results are navigable without a second lookup.
 
 > **LLM agent tip**: call `db_info()` before lineage queries to check that
 > `SqlColumn > 0` and `warnings` is empty. If `parse_quality["scripting_block"]`
@@ -183,19 +240,40 @@ Full option reference: [docs/cli.md](docs/cli.md)
 ```bash
 sqlcg install                          # register MCP server in Claude Code
 sqlcg db init                          # initialise graph database
-sqlcg index <path> --dialect <d>       # index SQL files
+sqlcg index <path> --dialect snowflake # index SQL files (snowflake is the tested dialect)
 sqlcg index <path> --dialect auto      # read dialect from .sqlcg.toml
+sqlcg index <path> --profile           # index + print per-stage timing and slowest files
+sqlcg reindex <path> --from <sha> --to <sha>  # incremental resync of only changed files
+sqlcg analyze unused                   # tables with no query references
+sqlcg analyze upstream/downstream      # trace lineage from the CLI
+sqlcg find table/column/pattern        # search the graph
 sqlcg watch <path>                     # watch for file changes
-sqlcg git install-hooks                # install post-checkout hook
+sqlcg git install-hooks                # install post-checkout + post-merge resync hooks
 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 version                          # show installed version
 ```
 
 ## Supported dialects
 
-`snowflake` · `bigquery` · `postgres` · `ansi` · `tsql` · `dbt` (via optional extra)
+sqlcg is built on [sqlglot](https://github.com/tobymao/sqlglot), so other dialects
+*can* be parsed in theory. Only Snowflake has been tested against a real corpus,
+though — the table reflects what's actually been exercised, not what sqlglot can do.
+
+| Dialect | Status |
+|---------|--------|
+| `snowflake` | ✅ Tested against a production DWH (~1,400 files) |
+| `bigquery` | ⚠️ Unproven — parses via sqlglot, lineage not validated |
+| `postgres` | ⚠️ Unproven — parses via sqlglot, lineage not validated |
+| `ansi` | ⚠️ Unproven — parses via sqlglot, lineage not validated |
+| `tsql` | ⚠️ Unproven — parses via sqlglot, lineage not validated |
+| `dbt` | ⚠️ Unproven — via optional extra, lineage not validated |
+
+Want another dialect properly supported? We'd be glad to collaborate — open an issue
+with a minimal, anonymised corpus we can develop and test against. Getting Snowflake
+right was real work, so a representative corpus is what makes the difference.
 
 ## Development
 

sql_code_graph-1.0.0.dist-info/RECORD

@@ -0,0 +1,63 @@
+sqlcg/__init__.py,sha256=2lT2oiKX19arg1oTOFf13dXA3qyyQNpRevdvKHZIOp4,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/db.py,sha256=Yd4ZDz1BFwjO4Lyt3NefQnowkjdUxFDFmsPykBVH2Pk,6518
+sqlcg/cli/commands/find.py,sha256=4cEWQ0otxNIzzwwzZ0WB_Tms0EoKzcFfhB3FJt8Q5V4,2025
+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/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/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
+sqlcg/core/neo4j_backend.py,sha256=AM1TncP9GBGph-rSHwalZPmGUV2kFILzaJP-PSB0UYw,8437
+sqlcg/core/queries.cypher,sha256=auWIPJeVjgykk6wqTRMoNQCwRhzG2ZhF4MRufso2KYA,4182
+sqlcg/core/queries.py,sha256=XBdQTBSsX3WUqO3AdX5EWYH435GDrbwEg1BR9AvJSSo,1880
+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/walker.py,sha256=C__JuDcTzKxFqVjGFRr5cj9hgxvf8zffTz-0HMn1qTY,1746
+sqlcg/indexer/watcher.py,sha256=mJQq1LASRLKKwhz0WhCUWPLLqyPR2_-FD_8efYU6gE8,8442
+sqlcg/lineage/__init__.py,sha256=Da1DlYwtK13WHv_RnHjAtNkHTOuFbhxqCjT1Le7DsWM,46
+sqlcg/lineage/aggregator.py,sha256=G1xsTjf981EVSgN1yIHcC_ecDvcTcSPvEp6Kb2HPXkY,4943
+sqlcg/lineage/schema_resolver.py,sha256=iXt6LYF6UVWsGUpcfbmjmGn9wCgXl721lTGf_8AaWcc,7320
+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/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=Xc80vlhKiJqbt4cT7UcpYKcYzV9rSqFyG0d_oTc-eJE,12627
+sqlcg/parsers/tsql_parser.py,sha256=RRj1pACtAk2tLTDaFWRYF67a0IDvaf5A1YQXWIz0bpQ,956
+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/skill.py,sha256=siAtrRdFHQnASe9nl33MvkTXXt9EgCB8id5i9AUq4XU,10718
+sqlcg/server/tools.py,sha256=Jh16fefXMmw0mYUejoIMAXlJoPAaQoUbgrCghsmHNLk,54892
+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/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,,

sqlcg/__init__.py

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

sqlcg/cli/commands/analyze.py

@@ -68,6 +68,30 @@ def impact(  # noqa: B008
         _print_table(results, ["id", "kind"])
 
 
+@app.command("failures")
+def failures(
+    cause: str | None = typer.Option(  # noqa: B008
+        None, "--cause", help="Filter by E-code bucket (e.g. E5, timeout)"
+    ),
+    limit: int = typer.Option(100, "--limit", help="Maximum rows to return"),  # noqa: B008
+) -> None:
+    """List files that failed to parse, with their dominant cause (E-code bucket).
+
+    Requires a graph indexed with sqlcg >= v3 (schema version 3). Re-index
+    with 'sqlcg db reset && sqlcg index <path>' if the graph was built with
+    an earlier version.
+    """
+    with get_backend() as backend:
+        cypher = (
+            f"MATCH (f:{NodeLabel.FILE}) WHERE f.parse_failed = true "
+            "AND ($cause IS NULL OR f.parse_cause = $cause) "
+            "RETURN f.path AS path, f.parse_cause AS cause "
+            f"ORDER BY f.parse_cause LIMIT {limit}"
+        )
+        rows = backend.run_read(cypher, {"cause": cause})
+        _print_table(rows, ["path", "cause"])
+
+
 @app.command("unused")
 def unused(
     threshold: int = typer.Option(0, "--threshold", help="Minimum reference count threshold"),

sqlcg/cli/commands/db.py

@@ -1,5 +1,6 @@
 """Database management commands."""
 
+import os
 import shutil
 
 import typer
@@ -16,8 +17,18 @@ console = Console()
 
 
 @app.command("init")
-def db_init() -> None:
+def db_init(
+    buffer_pool_size: int = typer.Option(
+        0,
+        "--buffer-pool-size",
+        help="KuzuDB buffer pool size in MB (0 = default). "
+        "Set to 256-512 on memory-constrained machines.",
+    ),
+) -> None:
     """Initialise the graph database (idempotent)."""
+    if buffer_pool_size > 0:
+        os.environ["SQLCG_BUFFER_POOL_MB"] = str(buffer_pool_size)
+
     db_path = get_db_path()
     db_path.parent.mkdir(parents=True, exist_ok=True)
     with get_backend() as backend:
@@ -40,11 +51,23 @@ def db_reset(  # noqa: B008
             )
         console.print(f"[yellow]Reset repo[/yellow] {repo}")
     else:
-        # Full reset — delete the DB file (close backend first to release file handle)
+        # Full reset — delete the DB. Kuzu may store it as a single file (current,
+        # e.g. 0.11.x) or a directory (older versions); also drop the .wal sidecar.
+        # shutil.rmtree silently no-ops on a regular file (NotADirectoryError +
+        # ignore_errors), so dispatch on the actual filesystem type.
         db_path = get_db_path()
-        if db_path.exists():
-            shutil.rmtree(str(db_path), ignore_errors=True)
-        console.print("[red]Database wiped[/red]")
+        removed = False
+        for target in (db_path, db_path.with_name(db_path.name + ".wal")):
+            if target.is_dir():
+                shutil.rmtree(str(target), ignore_errors=True)
+                removed = True
+            elif target.exists():
+                target.unlink()
+                removed = True
+        if removed:
+            console.print("[red]Database wiped[/red]")
+        else:
+            console.print("[yellow]Nothing to wipe — database does not exist[/yellow]")
 
 
 @app.command("info")
@@ -102,10 +125,20 @@ def db_info() -> None:
         edges_count = edges_result[0]["count"] if edges_result else 0
         console.print(f"  COLUMN_LINEAGE edges: {edges_count}")
 
+        # Print star resolution metrics (T-07)
+        from sqlcg.core.queries import COUNT_STAR_EXPANSIONS_QUERY, COUNT_STAR_SOURCES_QUERY
+
+        star_source_result = backend.run_read(COUNT_STAR_SOURCES_QUERY, {})
+        star_source_count = star_source_result[0]["n"] if star_source_result else 0
+        console.print(f"  STAR_SOURCE edges: {star_source_count}")
+
+        star_expansion_result = backend.run_read(COUNT_STAR_EXPANSIONS_QUERY, {})
+        star_expansion_count = star_expansion_result[0]["n"] if star_expansion_result else 0
+        console.print(f"  STAR_EXPANSION lineage edges: {star_expansion_count}")
+
         # Print parsing mode distribution
         mode_query = (
-            "MATCH (q:SqlQuery) RETURN q.parsing_mode AS mode, COUNT(q) AS cnt "
-            "ORDER BY cnt DESC"
+            "MATCH (q:SqlQuery) RETURN q.parsing_mode AS mode, COUNT(q) AS cnt ORDER BY cnt DESC"
         )
         mode_rows = backend.run_read(mode_query, {})
         if mode_rows and "mode" in mode_rows[0]:

sqlcg/cli/commands/gain.py

@@ -113,19 +113,12 @@ def gain_cmd(
         )
 
         # Section E: execute_cypher ratio
-        cypher_query = (
-            "SELECT COUNT(*) as count FROM tool_calls "
-            "WHERE tool_name = 'execute_cypher'"
-        )
+        cypher_query = "SELECT COUNT(*) as count FROM tool_calls WHERE tool_name = 'execute_cypher'"
         execute_cypher_count_result = metrics.execute_query(cypher_query)
         execute_cypher_count = (
-            execute_cypher_count_result[0][0]
-            if execute_cypher_count_result
-            else 0
-        )
-        execute_cypher_ratio = (
-            execute_cypher_count / total_calls if total_calls > 0 else 0
+            execute_cypher_count_result[0][0] if execute_cypher_count_result else 0
         )
+        execute_cypher_ratio = execute_cypher_count / total_calls if total_calls > 0 else 0
 
         # Section F: parse quality from graph
         parse_quality: dict[str, int] | None = None
@@ -137,9 +130,7 @@ def gain_cmd(
                     {},
                 )
                 if mode_rows and "mode" in mode_rows[0]:
-                    parse_quality = {
-                        str(r["mode"]): int(r["cnt"]) for r in mode_rows
-                    }
+                    parse_quality = {str(r["mode"]): int(r["cnt"]) for r in mode_rows}
         except Exception:
             pass  # graph not available — skip quality section
 
@@ -202,10 +193,7 @@ def gain_cmd(
             console.print("[bold cyan]E. Raw Cypher Usage[/bold cyan]")
             ratio_pct = execute_cypher_ratio * 100
             if execute_cypher_ratio > 0.3:
-                msg = (
-                    f"  [yellow]execute_cypher: {ratio_pct:.1f}% "
-                    "(high raw-Cypher usage)[/yellow]"
-                )
+                msg = f"  [yellow]execute_cypher: {ratio_pct:.1f}% (high raw-Cypher usage)[/yellow]"
                 console.print(msg)
             else:
                 console.print(f"  execute_cypher: {ratio_pct:.1f}%")

sqlcg/cli/commands/git.py

@@ -1,6 +1,7 @@
 """Git integration commands for sqlcg."""
 
 from pathlib import Path
+from typing import NamedTuple
 
 import typer
 from rich.console import Console
@@ -10,6 +11,71 @@ console = Console()
 app = typer.Typer(name="git", help="Git integration commands")
 
 
+class _HookSpec(NamedTuple):
+    filename: str
+    sentinel: str
+    script: str
+
+
+_HOOKS: list[_HookSpec] = [
+    _HookSpec(
+        filename="post-checkout",
+        sentinel="# sqlcg post-checkout hook",
+        script=(
+            "#!/bin/sh\n"
+            "# sqlcg post-checkout hook — incremental resync after branch switch\n"
+            "# $3 == 1 means branch checkout (not file checkout); skip file checkouts\n"
+            '[ "$3" = "1" ] || exit 0\n'
+            'sqlcg reindex --from "$1" --to "$2"'
+            ' "$(git rev-parse --show-toplevel)" --dialect auto --quiet || true\n'
+        ),
+    ),
+    _HookSpec(
+        filename="post-merge",
+        sentinel="# sqlcg post-merge hook",
+        script="""\
+#!/bin/sh
+# sqlcg post-merge hook — incremental resync after pull/merge
+# post-merge receives only $1 (squash flag), no old/new SHA; use stored-SHA delta
+sqlcg reindex "$(git rev-parse --show-toplevel)" --dialect auto --quiet || true
+""",
+    ),
+]
+
+
+def _install_single_hook(hooks_dir: Path, spec: _HookSpec) -> None:
+    """Install one git hook idempotently.
+
+    If the hook file already contains the sentinel, it is already installed — skip silently.
+    If the hook file exists without the sentinel, warn and print the script for manual append.
+    Otherwise, write the hook file and set 0o755.
+    """
+    hook_path = hooks_dir / spec.filename
+
+    if hook_path.exists():
+        existing_content = hook_path.read_text()
+        if spec.sentinel in existing_content:
+            # Already installed — idempotent, skip silently
+            return
+        else:
+            # Foreign hook without sqlcg sentinel
+            console.print(
+                f"[yellow]Warning: existing {spec.filename} hook found that was not created "
+                "by sqlcg.[/yellow]"
+            )
+            console.print(
+                f"[yellow]To integrate sqlcg, manually append the following to "
+                f".git/hooks/{spec.filename}:[/yellow]"
+            )
+            console.print("")
+            console.print("[cyan]" + spec.script.rstrip() + "[/cyan]")
+            return
+
+    hook_path.write_text(spec.script)
+    hook_path.chmod(0o755)
+    console.print(f"[green]Installed git hook:[/green] .git/hooks/{spec.filename}")
+
+
 @app.command("install-hooks")
 def install_hooks(
     repo: Path | None = typer.Option(  # noqa: B008
@@ -18,8 +84,9 @@ def install_hooks(
 ) -> None:
     """Install git hooks for sqlcg integration.
 
-    Writes a post-checkout hook that triggers graph resync after branch switches.
-    Idempotent: running multiple times produces one hook entry.
+    Writes a post-checkout hook that triggers incremental resync after branch switches
+    and a post-merge hook that triggers resync after pulls/merges.
+    Idempotent: running multiple times produces one hook entry per hook.
     """
     if repo is None:
         repo = Path.cwd()
@@ -33,41 +100,5 @@ def install_hooks(
 
     hooks_dir.mkdir(parents=True, exist_ok=True)
 
-    hook_path = hooks_dir / "post-checkout"
-    hook_sentinel = "# sqlcg post-checkout hook"
-
-    # Hook script content
-    hook_script = """#!/bin/sh
-# sqlcg post-checkout hook — resync graph after branch switch
-# $3 == 1 means branch checkout (not file checkout); skip file checkouts
-[ "$3" = "1" ] || exit 0
-sqlcg index "$(git rev-parse --show-toplevel)" --dialect auto --quiet || true
-"""
-
-    # Check if hook already exists
-    if hook_path.exists():
-        existing_content = hook_path.read_text()
-        if hook_sentinel in existing_content:
-            # Already installed, idempotent: skip silently
-            return
-        else:
-            # Existing hook without sqlcg sentinel
-            console.print(
-                "[yellow]Warning: existing post-checkout hook found that was not created "
-                "by sqlcg.[/yellow]"
-            )
-            console.print(
-                "[yellow]To integrate sqlcg, manually append the following to "
-                ".git/hooks/post-checkout:[/yellow]"
-            )
-            console.print("")
-            console.print("[cyan]" + hook_script.rstrip() + "[/cyan]")
-            return
-
-    # Write hook script
-    hook_path.write_text(hook_script)
-
-    # Make it executable
-    hook_path.chmod(0o755)
-
-    console.print("[green]Installed git hook:[/green] .git/hooks/post-checkout")
+    for spec in _HOOKS:
+        _install_single_hook(hooks_dir, spec)