sql-code-graph 0.2.1__py3-none-any.whl

sql_code_graph-0.2.1.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: sql-code-graph
+Version: 0.2.1
+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
+Project-URL: Issues, https://github.com/Warhorze/sql-code-graph/issues
+Project-URL: Changelog, https://github.com/Warhorze/sql-code-graph/blob/master/CHANGELOG.md
+Author-email: wesley <rademakerwesley@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: kuzu==0.11.3
+Requires-Dist: mcp<2.0,>=1.27.0
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: sqlglot==30.6.0
+Requires-Dist: sqlglotc==30.6.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: watchdog>=3.0.0
+Provides-Extra: dbt
+Requires-Dist: dbt-core>=1.7; extra == 'dbt'
+Provides-Extra: neo4j
+Requires-Dist: neo4j>=5.15.0; extra == 'neo4j'
+Provides-Extra: snowflake
+Requires-Dist: acryl-datahub<0.15.0,>=0.14.0; extra == 'snowflake'
+Description-Content-Type: text/markdown
+
+# sql-code-graph
+
+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
+queries as MCP tools — so Claude can answer questions like *"what tables does
+this view depend on?"* or *"where is `orders.customer_id` derived from?"*
+without reading every file.
+
+## Quick start
+
+```bash
+pip install sql-code-graph        # or: uvx sql-code-graph (no install needed)
+sqlcg install                     # register MCP server in Claude Code
+```
+
+Restart Claude Code, then inside your project ask:
+
+```
+Index my SQL files at ./sql --dialect snowflake
+```
+
+That's it. The MCP tools are now available to Claude in every conversation
+for that project.
+
+## Full setup (recommended)
+
+```bash
+# 1. Install
+pip install sql-code-graph
+
+# 2. Register with Claude Code (~/.claude/settings.json)
+sqlcg install
+
+# 3. Restart Claude Code
+
+# 4. Index your SQL repo
+# 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
+
+# 5. (Optional) Keep the graph fresh on branch switches
+cd /your/sql/repo
+sqlcg git install-hooks
+```
+
+Step 5 installs a `post-checkout` git hook that re-indexes automatically
+whenever you switch branches. Without it the graph may be stale after a
+`git checkout` until you re-run `sqlcg index` manually.
+
+## Dialect config
+
+To avoid passing `--dialect` every time, create `.sqlcg.toml` in your repo root:
+
+```toml
+[sqlcg]
+dialect = "snowflake"   # snowflake | bigquery | postgres | ansi
+```
+
+The git hook and `sqlcg index --dialect auto` both read this file.
+
+## Add to your project CLAUDE.md (recommended)
+
+Adding a short note to your project's `CLAUDE.md` helps Claude know the tools
+are available and when to use them:
+
+```markdown
+## SQL lineage
+This project uses sql-code-graph. MCP tools are available:
+- `index_repo` — index or re-index a directory of SQL files
+- `find_table_usages` — find all queries that read a table
+- `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
+```
+
+The MCP server works without this — Claude can discover the tools on its own —
+but the CLAUDE.md snippet ensures they get used proactively.
+
+## 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 |
+| `get_upstream_dependencies(table_col)` | Full upstream dependency chain |
+| `get_downstream_dependencies(table_col)` | Full downstream dependency chain |
+| `search_sql_pattern(query)` | Full-text search across indexed SQL |
+| `list_dialects_and_repos()` | List indexed repos and dialects |
+| `execute_cypher(query)` | Raw Cypher query against the graph |
+
+## CLI reference
+
+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 auto      # read dialect from .sqlcg.toml
+sqlcg watch <path>                     # watch for file changes
+sqlcg git install-hooks                # install post-checkout hook
+sqlcg gain                             # show usage metrics
+sqlcg report                           # generate FP/error report
+sqlcg mcp start                        # start MCP server manually
+sqlcg version                          # show installed version
+```
+
+## Supported dialects
+
+`snowflake` · `bigquery` · `postgres` · `ansi` · `tsql` · `dbt` (via optional extra)
+
+## Development
+
+```bash
+git clone https://github.com/Warhorze/sql-code-graph
+cd sql-code-graph
+uv sync --all-extras
+uv run pytest tests/unit
+```
+
+## Issues
+
+Bug reports and feature requests: [github.com/Warhorze/sql-code-graph/issues](https://github.com/Warhorze/sql-code-graph/issues)
+
+Questions and discussion: [github.com/Warhorze/sql-code-graph/discussions](https://github.com/Warhorze/sql-code-graph/discussions)
+
+## License
+
+MIT

sql_code_graph-0.2.1.dist-info/RECORD

@@ -0,0 +1,55 @@
+sqlcg/__init__.py,sha256=UOfmI89XKJTvVCisH5LdsjbnKEv-ESDsi5XGcM4VisY,115
+sqlcg/__main__.py,sha256=1YoFLcqEgTwYq1J3TbUwpkdG0zeeLIf2fJvwWI-CLFU,109
+sqlcg/cli/__init__.py,sha256=W8fD0LpMq2xm_5WKGNMvJh2WBL1ho5E8hUeAqXQYT1g,28
+sqlcg/cli/main.py,sha256=4FvjYUmiuX6Zij0zuiMwWJTOXb_OSQe60poQQ3W6qSA,987
+sqlcg/cli/commands/__init__.py,sha256=oSHtr6VD-jNubOjuCQyZj2tBppjMEpQDh-IGQ8of9eA,30
+sqlcg/cli/commands/analyze.py,sha256=Vurb_PdHQ6Aw5ZRFEbQwUiylkz5D4j849EwtIqgagHk,3168
+sqlcg/cli/commands/db.py,sha256=iFr8re4z_0qxz_3LTH_5pQoleIQ3cHJy9eeeHrrEp4o,2866
+sqlcg/cli/commands/find.py,sha256=4cEWQ0otxNIzzwwzZ0WB_Tms0EoKzcFfhB3FJt8Q5V4,2025
+sqlcg/cli/commands/gain.py,sha256=FXPF8vEc0S03FN-fiUO3YauOsDe3p9yp4Wy9entj8tE,5793
+sqlcg/cli/commands/git.py,sha256=d1LDKaqMfaW28U3rCWjaEe-GB5RybJWsz36iBkNXF9Y,2253
+sqlcg/cli/commands/index.py,sha256=u0jL9PeDKloTfEBWpdcpH7P7ASTakFsiEuEEMObjm0U,3208
+sqlcg/cli/commands/install.py,sha256=499JWrosmceKmSOmGohABj0M0jvrcURyt4tHfEXNoTQ,1964
+sqlcg/cli/commands/mcp.py,sha256=z_K_ARmuAnjAxWD-CXkjGjXI-DUgWV19yzjJW2cl8wI,1484
+sqlcg/cli/commands/report.py,sha256=JU0qjyMxwOukE7bN3XvvIzOI7zMg_Gsnvk_8F6pKNpA,4915
+sqlcg/cli/commands/watch.py,sha256=KOlQ0ZoYnzTxqsSnJvHdr656vaG6zNRfKRefyqkTJzg,1889
+sqlcg/core/__init__.py,sha256=uNsJCrCMVWVT80sHPtI_f39BYqIf5N0i6LSq8x8HsyI,283
+sqlcg/core/config.py,sha256=acrNRlOTIEKr2ttWFqVToiN-9Z9csbBCTJvQLtjCI3g,3004
+sqlcg/core/graph_db.py,sha256=BN3QUD8hNVY5I7qsKj5zvl8v2uT_hswKvvkmwZ3mClA,5551
+sqlcg/core/jobs.py,sha256=Je-fCdSKRgiSsv1W8SgNAlp36a7t7-pJZ-qKPbka9OE,3298
+sqlcg/core/kuzu_backend.py,sha256=6ymm1Q6pj3jw4luKV5q0-qFpWh3KZmQiktliHPc-YoU,9656
+sqlcg/core/neo4j_backend.py,sha256=Tl2_jGv086DTJYQBixv-Tm_misyd_5-iEb_UuCjKk_I,7058
+sqlcg/core/queries.py,sha256=qxoMH75yGWLwNH9Ki9l9NV9IzOsH6fgdAsHdewLRn-o,2733
+sqlcg/core/schema.cypher,sha256=BNMbXaHtINT3uaW0vlnBrG8DLa6k8i-CfOkrF-ZVo_U,2220
+sqlcg/core/schema.py,sha256=miHPMh2hSQueNdGfD-7pNXk0EIDsCkEh431eI9_iTEI,1269
+sqlcg/indexer/__init__.py,sha256=Wh20Unz2OHs1oIyWLrpurPAasF0BET2g4iXtNk7mh2U,56
+sqlcg/indexer/dbt_adapter.py,sha256=EB5x1WU5Z9d-I97ADDj88S_hG1C4z4nbrv8JUCzXfy8,686
+sqlcg/indexer/indexer.py,sha256=rRu51-BOIJiRaitE2V-f_VffwULlWtN5sG1kEplw8_s,11338
+sqlcg/indexer/walker.py,sha256=WpF5mJvc6ayN_DJ52w2UQnNxXeqh03QbBeYEqrKpAZI,1752
+sqlcg/indexer/watcher.py,sha256=OaYiQTQMIPdVQEtuJqY7Z9zCi8vr2UqWOkm4Ygp_Ap4,6697
+sqlcg/lineage/__init__.py,sha256=Da1DlYwtK13WHv_RnHjAtNkHTOuFbhxqCjT1Le7DsWM,46
+sqlcg/lineage/aggregator.py,sha256=wEQmZSL0COKKRwQpfO5skL427aJlsDa4qiH-UvSSs24,1905
+sqlcg/lineage/schema_resolver.py,sha256=e6PU99SO6L-bIaFLwOekarhass-SeGoeVdB9PgbLSjg,6803
+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=S82CfyQlB2VCwU4eKJOXh4blFQBGtz5q0wuxHrFFrn8,6539
+sqlcg/parsers/base.py,sha256=a7YDijigCkeGrLJjgnckp78mKtv9o6O75s9iKHLu5qc,14812
+sqlcg/parsers/bigquery_parser.py,sha256=6VfKhTUVLbRdKmQieEe9S8oxv6-zzqXw4t6DeGRUlEs,2624
+sqlcg/parsers/postgres_parser.py,sha256=-pyBr-KU4JGRurxsvJmK5jgdTcNesSDClTzEsl4o2A8,744
+sqlcg/parsers/registry.py,sha256=7l5ODWszz6CDC_5ZhhQkST9U-pvqJ-i6D0GqPXwcWhE,1325
+sqlcg/parsers/snowflake_parser.py,sha256=oNfKAA95AJpy292tp0I3o5vuT7tf6a_4dtUJBSErfBg,5463
+sqlcg/parsers/tsql_parser.py,sha256=zZQ6CqV3lXNUG_FOeWRwv9AEXhAeAw4LcTDAaxayTW4,754
+sqlcg/server/__init__.py,sha256=n4wuNE7xyJIJxJZBtmtdccCMQfvTdF-IqIaZVbC4FC4,35
+sqlcg/server/exceptions.py,sha256=EONw34icOByCTpppSQrvQBW6asc4hfqaGDCAFjv96II,469
+sqlcg/server/models.py,sha256=Tt1EoD7hYsQ0Q92RDkjEhoWwhDGkqA3jehauSvOVD0w,2812
+sqlcg/server/server.py,sha256=2EwKGehcIdKqCjZagbv8VrvnVCp-D5Lh-z38FFHRcN8,1723
+sqlcg/server/tools.py,sha256=YBLbTdxCY0r39p8jjENps9t6HftHk-6sFVF-y5vzMF8,19704
+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-0.2.1.dist-info/METADATA,sha256=BbaL4fmjPJ2-NkLmiGU4-dvMOlZi1dL_CioMI3bdTvY,5920
+sql_code_graph-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sql_code_graph-0.2.1.dist-info/entry_points.txt,sha256=Wfe49sVzV9p4eVFGo5RxcV-frr3HOP0yzzst8JBxQLQ,46
+sql_code_graph-0.2.1.dist-info/RECORD,,

sql_code_graph-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sql_code_graph-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sqlcg = sqlcg.cli.main:main

sqlcg/__init__.py

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

sqlcg/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for sqlcg CLI."""
+
+if __name__ == "__main__":
+    from sqlcg.cli.main import main
+
+    main()

sqlcg/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI module for sqlcg."""

sqlcg/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands for sqlcg."""

sqlcg/cli/commands/analyze.py

@@ -0,0 +1,93 @@
+"""Analyze command for lineage analysis."""
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from sqlcg.core.config import get_backend
+from sqlcg.core.schema import NodeLabel, RelType
+
+app = typer.Typer(help="Lineage analysis")
+console = Console()
+
+
+@app.command("upstream")
+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
+) -> None:
+    """Trace upstream column lineage."""
+    # Bounds check for depth to prevent performance DoS
+    if depth < 1 or depth > 100:
+        console.print("[red]Error: --depth must be between 1 and 100[/red]")
+        raise typer.Exit(1)
+
+    with get_backend() as backend:
+        results = backend.run_read(
+            f"MATCH p=(c:{NodeLabel.COLUMN} {{id: $ref}})"
+            f"<-[:{RelType.COLUMN_LINEAGE}*1..{depth}]-(src) "
+            "RETURN src.id AS id LIMIT 100",
+            {"ref": ref},
+        )
+        _print_table(results, ["id"])
+
+
+@app.command("downstream")
+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
+) -> None:
+    """Trace downstream column lineage."""
+    # Bounds check for depth to prevent performance DoS
+    if depth < 1 or depth > 100:
+        console.print("[red]Error: --depth must be between 1 and 100[/red]")
+        raise typer.Exit(1)
+
+    with get_backend() as backend:
+        results = backend.run_read(
+            f"MATCH p=(c:{NodeLabel.COLUMN} {{id: $ref}})"
+            f"-[:{RelType.COLUMN_LINEAGE}*1..{depth}]->(dst) "
+            "RETURN dst.id AS id LIMIT 100",
+            {"ref": ref},
+        )
+        _print_table(results, ["id"])
+
+
+@app.command("impact")
+def impact(  # noqa: B008
+    table: str = typer.Argument(..., help="Table name to analyze"),  # noqa: B008
+) -> None:
+    """Show all queries impacted by a table."""
+    with get_backend() as backend:
+        results = backend.run_read(
+            f"MATCH (t:{NodeLabel.TABLE} {{qualified: $t}})"
+            f"<-[:{RelType.SELECTS_FROM}]-(q:{NodeLabel.QUERY}) "
+            "RETURN q.id AS id, q.kind AS kind LIMIT 100",
+            {"t": table},
+        )
+        _print_table(results, ["id", "kind"])
+
+
+@app.command("unused")
+def unused(
+    threshold: int = typer.Option(0, "--threshold", help="Minimum reference count threshold"),
+) -> None:
+    """Find tables with no query references."""
+    with get_backend() as backend:
+        results = backend.run_read(
+            f"MATCH (t:{NodeLabel.TABLE}) WHERE NOT (t)<-[:{RelType.SELECTS_FROM}]-() "
+            "RETURN t.qualified AS qualified LIMIT 100",
+            {},
+        )
+        _print_table(results, ["qualified"])
+
+
+def _print_table(rows: list[dict], columns: list[str]) -> None:
+    """Print results as a Rich table."""
+    if not rows:
+        console.print("[yellow]No results[/yellow]")
+        return
+    t = Table(*columns)
+    for row in rows:
+        t.add_row(*[str(row.get(c, "")) for c in columns])
+    console.print(t)

sqlcg/cli/commands/db.py

@@ -0,0 +1,83 @@
+"""Database management commands."""
+
+import shutil
+
+import typer
+from rich.console import Console
+
+from sqlcg.core.config import get_backend, get_db_path
+from sqlcg.core.schema import NodeLabel
+from sqlcg.utils.logging import getLogger
+
+logger = getLogger(__name__)
+
+app = typer.Typer(help="Database management commands")
+console = Console()
+
+
+@app.command("init")
+def db_init() -> None:
+    """Initialise the graph database (idempotent)."""
+    db_path = get_db_path()
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    with get_backend() as backend:
+        backend.init_schema()
+        version = backend.get_schema_version()
+        console.print(f"[green]Database initialised[/green] at {db_path} (schema v{version})")
+
+
+@app.command("reset")
+def db_reset(  # noqa: B008
+    repo: str | None = typer.Option(None, "--repo", help="Reset only this repo path"),  # noqa: B008
+) -> None:
+    """Wipe the database or a single repo's subgraph."""
+    if repo:
+        # Delete all nodes for this repo (use run_write for mutation)
+        with get_backend() as backend:
+            backend.run_write(
+                "MATCH (r:Repo {path: $p}) DETACH DELETE r",
+                {"p": repo},
+            )
+        console.print(f"[yellow]Reset repo[/yellow] {repo}")
+    else:
+        # Full reset — delete the DB file (close backend first to release file handle)
+        db_path = get_db_path()
+        if db_path.exists():
+            shutil.rmtree(str(db_path), ignore_errors=True)
+        console.print("[red]Database wiped[/red]")
+
+
+@app.command("info")
+def db_info() -> None:
+    """Show database stats."""
+    with get_backend() as backend:
+        version = backend.get_schema_version() or "unknown"
+        console.print(f"Schema version: {version}")
+
+        # Show node counts for all labels
+        for label in NodeLabel:
+            try:
+                result = backend.run_read(f"MATCH (n:{label}) RETURN COUNT(*) AS count", {})
+                count = result[0]["count"] if result else 0
+                console.print(f"  {label}: {count}")
+            except Exception as e:
+                # Log unexpected exceptions instead of silently skipping
+                logger.error(f"Error getting count for {label}: {e}")
+                console.print(f"  [red]{label}: error[/red]")
+
+
+@app.command("list-repos")
+def list_repos() -> None:
+    """List all indexed repositories."""
+    with get_backend() as backend:
+        result = backend.run_read("MATCH (r:Repo) RETURN r.path AS path, r.name AS name", {})
+
+        if not result:
+            console.print("[yellow]No repositories indexed[/yellow]")
+        else:
+            from rich.table import Table
+
+            table = Table("Path", "Name")
+            for row in result:
+                table.add_row(str(row.get("path", "")), str(row.get("name", "")))
+            console.print(table)

sqlcg/cli/commands/find.py

@@ -0,0 +1,63 @@
+"""Find command for searching the graph."""
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from sqlcg.core.config import get_backend
+from sqlcg.core.schema import NodeLabel
+
+app = typer.Typer(help="Search the graph")
+console = Console()
+
+
+@app.command("table")
+def find_table(  # noqa: B008
+    name: str = typer.Argument(..., help="Table name to search for"),  # noqa: B008
+) -> None:
+    """Find a table by name."""
+    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},
+        )
+        _print_table(results, ["qualified", "kind"])
+
+
+@app.command("column")
+def find_column(  # noqa: B008
+    ref: str = typer.Argument(..., help="Column reference (table.column)"),  # noqa: B008
+) -> None:
+    """Find a column by table.column reference."""
+    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",
+            {"ref": ref},
+        )
+        _print_table(results, ["id"])
+
+
+@app.command("pattern")
+def find_pattern(  # noqa: B008
+    pattern: str = typer.Argument(..., help="SQL pattern to search for"),  # noqa: B008
+) -> None:
+    """Find queries containing a SQL pattern."""
+    with get_backend() as backend:
+        results = backend.run_read(
+            f"MATCH (q:{NodeLabel.QUERY}) WHERE q.sql CONTAINS $pattern "
+            "RETURN q.id AS id, q.kind AS kind LIMIT 50",
+            {"pattern": pattern},
+        )
+        _print_table(results, ["id", "kind"])
+
+
+def _print_table(rows: list[dict], columns: list[str]) -> None:
+    """Print results as a Rich table."""
+    if not rows:
+        console.print("[yellow]No results[/yellow]")
+        return
+    t = Table(*columns)
+    for row in rows:
+        t.add_row(*[str(row.get(c, "")) for c in columns])
+    console.print(t)

sqlcg/cli/commands/gain.py

@@ -0,0 +1,169 @@
+"""The sqlcg gain command — view metrics and feedback analytics."""
+
+import json
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from sqlcg.metrics.store import MetricsStore
+from sqlcg.utils.logging import getLogger
+
+logger = getLogger(__name__)
+console = Console()
+
+
+def gain_cmd(
+    json_output: bool = typer.Option(  # noqa: B008
+        False,
+        "--json",
+        help="Output metrics as JSON",
+    ),
+    _metrics_path: Path | None = None,  # For testing only
+) -> None:
+    """Show metrics and feedback analytics.
+
+    Displays:
+    - Section A: Total MCP tool calls and calls in the last 7 days
+    - Section B: Parse success trend (last 5 index runs)
+    - Section C: True positive feedback rate (if ≥5 samples)
+    - Section D: Top 3 most-called tools
+
+    All metrics are opt-in via SQLCG_METRICS environment variable.
+    If no metrics have been collected, shows a message and exits 0.
+    """
+    if _metrics_path is None:
+        metrics_path = Path.home() / ".sqlcg" / "metrics.db"
+    else:
+        metrics_path = _metrics_path
+
+    if not metrics_path.exists():
+        if json_output:
+            console.print(
+                json.dumps(
+                    {
+                        "total_calls": 0,
+                        "last_7d_calls": 0,
+                        "index_runs": 0,
+                        "feedback_tp": 0,
+                        "feedback_total": 0,
+                        "top_tools": [],
+                    }
+                )
+            )
+        else:
+            console.print("No metrics collected yet.")
+        return
+
+    try:
+        metrics = MetricsStore(metrics_path)
+        metrics.init_schema()  # Ensure schema exists
+
+        # Section A: Total calls and last 7 days
+        all_calls = metrics.execute_query("SELECT COUNT(*) as count FROM tool_calls")
+        total_calls = all_calls[0][0] if all_calls else 0
+
+        cutoff_date = (datetime.now(UTC) - timedelta(days=7)).isoformat()
+        last_7d = metrics.execute_query(
+            "SELECT COUNT(*) as count FROM tool_calls WHERE timestamp > ?",
+            (cutoff_date,),
+        )
+        last_7d_calls = last_7d[0][0] if last_7d else 0
+
+        # Section B: Parse success (last 5 index runs)
+        index_runs = metrics.execute_query(
+            """
+            SELECT files_parsed, parse_errors
+            FROM index_runs
+            ORDER BY timestamp DESC
+            LIMIT 5
+            """
+        )
+
+        # Section C: TP feedback rate
+        feedback_counts = metrics.execute_query(
+            """
+            SELECT
+                SUM(CASE WHEN label = 'TP' THEN 1 ELSE 0 END) as tp_count,
+                COUNT(*) as total
+            FROM feedback
+            """
+        )
+        tp_count = feedback_counts[0][0] or 0 if feedback_counts else 0
+        fb_total = feedback_counts[0][1] or 0 if feedback_counts else 0
+
+        # Section D: Top 3 tools
+        top_tools = metrics.execute_query(
+            """
+            SELECT tool_name, COUNT(*) as count
+            FROM tool_calls
+            GROUP BY tool_name
+            ORDER BY count DESC
+            LIMIT 3
+            """
+        )
+
+        if json_output:
+            console.print(
+                json.dumps(
+                    {
+                        "total_calls": total_calls,
+                        "last_7d_calls": last_7d_calls,
+                        "index_runs": len(index_runs),
+                        "feedback_tp": tp_count,
+                        "feedback_total": fb_total,
+                        "top_tools": [{"name": row[0], "count": row[1]} for row in top_tools],
+                    }
+                )
+            )
+        else:
+            # Human-readable output
+            console.print("\n[bold]SQL Code Graph Metrics[/bold]")
+            console.print()
+
+            # Section A
+            console.print("[bold cyan]A. Tool Calls[/bold cyan]")
+            console.print(f"  Total: {total_calls}")
+            console.print(f"  Last 7 days: {last_7d_calls}")
+            console.print()
+
+            # Section B
+            console.print("[bold cyan]B. Index Runs[/bold cyan]")
+            if index_runs:
+                console.print(f"  Recent runs: {len(index_runs)}")
+                total_files = sum(row[0] for row in index_runs)
+                total_errors = sum(row[1] for row in index_runs)
+                success_rate = (
+                    100 * (total_files - total_errors) / total_files if total_files > 0 else 0
+                )
+                console.print(f"  Success rate (last 5): {success_rate:.1f}%")
+            else:
+                console.print("  No index runs recorded")
+            console.print()
+
+            # Section C
+            if fb_total >= 5:
+                tp_rate = 100 * tp_count / fb_total if fb_total > 0 else 0
+                console.print("[bold cyan]C. Feedback[/bold cyan]")
+                console.print(f"  True positive rate: {tp_rate:.1f}% ({tp_count}/{fb_total})")
+            else:
+                console.print("[bold cyan]C. Feedback[/bold cyan]")
+                console.print(f"  Samples: {fb_total}/5 (need 5 to show TP rate)")
+            console.print()
+
+            # Section D
+            if top_tools:
+                console.print("[bold cyan]D. Top Tools[/bold cyan]")
+                for i, (name, count) in enumerate(top_tools, 1):
+                    console.print(f"  {i}. {name}: {count}")
+            console.print()
+
+        metrics.close()
+
+    except Exception as exc:
+        logger.error(f"Failed to generate metrics report: {exc}")
+        if json_output:
+            console.print(json.dumps({"error": str(exc)}))
+        else:
+            console.print(f"[red]Error: {exc}[/red]")