sql-code-graph 1.34.4__tar.gz → 1.35.1__tar.gz

{sql_code_graph-1.34.4 → sql_code_graph-1.35.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-code-graph
-Version: 1.34.4
+Version: 1.35.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

{sql_code_graph-1.34.4 → sql_code_graph-1.35.1}/docs/cli.md

@@ -17,6 +17,7 @@ bash scripts/generate_cli_docs.sh
 | `watch` | Watch a directory and re-index on SQL file changes. |
 | `gain` | Show metrics and feedback analytics. |
 | `report` | Generate a metrics report with FP clusters and parse error patterns. |
+| `viz` | Generate a self-contained graph-explorer HTML from the live graph. |
 | `install` | Register sqlcg as an MCP server in Claude Code. |
 | `uninstall` | Uninstall sqlcg from Claude Code and optionally clean up resources. |
 | `version` | Show version. |
@@ -187,6 +188,33 @@ If no metrics database exists, prints a message and exits 0.
 | --stdout | BOOLEAN | No | No | False | Print to stdout instead of file |
 | --output, -o | PATH | No | No |  | Output file path |
 
+## `sqlcg viz`
+
+```bash
+sqlcg viz [OPTIONS]
+```
+
+Generate a self-contained graph-explorer HTML from the live graph.
+
+Reads the graph via the server-aware routed-read path (never a direct DB
+open). The emitted file inlines the force-graph library plus the baked node/
+edge/adjacency data and the tag/job facets — no external resources — so it
+opens by double-click on Windows.
+
+The client-side filter composes schema ∩ kind ∩ tag (multi-select per facet,
+union within a facet, intersection across) plus a job dropdown; an edge
+renders only when both endpoints are visible. Node kinds table/view/temp are
+ON by default, cte/derived OFF (switchable).
+
+### Options
+
+| Option | Type | Required | Repeatable | Default | Description |
+| --- | --- | --- | --- | --- | --- |
+| --tags | PATH | No | No |  | BYO tags CSV (pattern,label[,color]; header required). The 'tag' facet drives the legend swatches (color + filter). Patterns are fnmatch globs (*, ?, [seq]) matched case-insensitively against the qualified table name. Many-to-many. Omit to hide the tag legend. |
+| --jobs | PATH | No | No |  | BYO jobs CSV, same shape as --tags. The 'job' facet drives the job dropdown (filter only). Omit to leave the dropdown empty. |
+| --out | PATH | No | No |  | Output HTML path (default: table_graph.html in the current directory). |
+| --config-dir | PATH | No | No | . | Directory searched for .sqlcg.toml ([sqlcg.viz] schemas). |
+
 ## `sqlcg install`
 
 ```bash

sql_code_graph-1.35.1/plan/metrics/pr_b_phantom_after.json

@@ -0,0 +1,32 @@
+{"total_calls": 1476, "last_7d_calls": 1476, "index_runs": 5, "feedback_tp": 0, 
+"feedback_total": 0, "top_tools": [{"name": "execute_sql", "count": 496}, 
+{"name": "trace_column_lineage", "count": 389}, {"name": 
+"list_dialects_and_repos", "count": 127}], "execute_sql_ratio": 0.34, 
+"parse_quality": {"sqlglot": 5166, "scripting": 20, "dynamic_sql": 3}, 
+"coverage": {"catalogued_tables": 5800, "total_tables": 6552, "good_edges": 
+52657, "total_edges": 60805, "phantom_edges": 12241, "blindspot_tables": 628, 
+"good_edges_strict": 48140, "edge_health_strict_pct": 79.17, 
+"good_edges_scoped": 37460, "total_edges_scoped": 38009, 
+"edge_health_scoped_pct": 98.56, "phantom_confirmed": 11701, 
+"phantom_contradicted": 352, "phantom_unverified": 188, "top_blindspot_tables": 
+[{"table": "ba.wtfa_kpi_datum_klant", "bad_edges": 70}, {"table": 
+"ba.wtfs_voorraad_dagstand", "bad_edges": 55}, {"table": 
+"ba.wtfs_voorraad_zondagstand", "bad_edges": 55}, {"table": 
+"da.rtgmd_postnl_customer_usage", "bad_edges": 43}, {"table": 
+"da.rtgmd_postnl_athome_3s", "bad_edges": 33}, {"table": 
+"wtfe_kpi_voorraad_artikel_voorraadlocatie", "bad_edges": 32}, {"table": 
+"da.rtgmd_postnl_facturen", "bad_edges": 30}, {"table": "da.hthyb_pages", 
+"bad_edges": 23}, {"table": "da.rtgmd_dhb_extra_kosten", "bad_edges": 19}, 
+{"table": "da.hthyb_page_brandplacement", "bad_edges": 17}], 
+"blindspot_tables_for_80pct": 17, "files_indexed": 1335, "indexed_sha": 
+"fdf1b551a34601a6cf3ce1c8b9f76e27ce2753e6", "db_path": 
+"/tmp/sqlcg-gain-after.db", "index_timestamp": 1781466521.041257, 
+"degraded_parse_total": 5189, "degraded_parse_queries": 20, 
+"degraded_parse_by_dir": {"etl": {"degraded": 1, "total": 2776}, "ddl": 
+{"degraded": 19, "total": 2413}}, "zero_edge_write_queries": 1034, 
+"total_write_queries": 2323, "cte_key_collisions": 0, 
+"rescuable_unqualified_edges": 125, "info_schema_has_column_rows": 100193, 
+"cte_source_gap_writes": 0, "resolvable_write_col_edges": 36936, 
+"transitive_col_edges": 4168, "qualify_failed_statements": 9, 
+"tool_version_stale": false, "indexed_tool_version": "1.34.5", 
+"running_tool_version": "1.34.5"}}

sql_code_graph-1.35.1/plan/metrics/pr_b_phantom_before.json

@@ -0,0 +1,32 @@
+{"total_calls": 1476, "last_7d_calls": 1476, "index_runs": 5, "feedback_tp": 0, 
+"feedback_total": 0, "top_tools": [{"name": "execute_sql", "count": 496}, 
+{"name": "trace_column_lineage", "count": 389}, {"name": 
+"list_dialects_and_repos", "count": 127}], "execute_sql_ratio": 0.34, 
+"parse_quality": {"sqlglot": 5166, "scripting": 20, "dynamic_sql": 3}, 
+"coverage": {"catalogued_tables": 5800, "total_tables": 6581, "good_edges": 
+52669, "total_edges": 60817, "phantom_edges": 12241, "blindspot_tables": 628, 
+"good_edges_strict": 48140, "edge_health_strict_pct": 79.16, 
+"good_edges_scoped": 37460, "total_edges_scoped": 38009, 
+"edge_health_scoped_pct": 98.56, "phantom_confirmed": 11701, 
+"phantom_contradicted": 352, "phantom_unverified": 188, "top_blindspot_tables": 
+[{"table": "ba.wtfa_kpi_datum_klant", "bad_edges": 70}, {"table": 
+"ba.wtfs_voorraad_dagstand", "bad_edges": 55}, {"table": 
+"ba.wtfs_voorraad_zondagstand", "bad_edges": 55}, {"table": 
+"da.rtgmd_postnl_customer_usage", "bad_edges": 43}, {"table": 
+"da.rtgmd_postnl_athome_3s", "bad_edges": 33}, {"table": 
+"wtfe_kpi_voorraad_artikel_voorraadlocatie", "bad_edges": 32}, {"table": 
+"da.rtgmd_postnl_facturen", "bad_edges": 30}, {"table": "da.hthyb_pages", 
+"bad_edges": 23}, {"table": "da.rtgmd_dhb_extra_kosten", "bad_edges": 19}, 
+{"table": "da.hthyb_page_brandplacement", "bad_edges": 17}], 
+"blindspot_tables_for_80pct": 17, "files_indexed": 1335, "indexed_sha": 
+"fdf1b551a34601a6cf3ce1c8b9f76e27ce2753e6", "db_path": 
+"/tmp/sqlcg-gain-before.db", "index_timestamp": 1781466329.8251324, 
+"degraded_parse_total": 5189, "degraded_parse_queries": 20, 
+"degraded_parse_by_dir": {"etl": {"degraded": 1, "total": 2776}, "ddl": 
+{"degraded": 19, "total": 2413}}, "zero_edge_write_queries": 1034, 
+"total_write_queries": 2323, "cte_key_collisions": 0, 
+"rescuable_unqualified_edges": 125, "info_schema_has_column_rows": 100193, 
+"cte_source_gap_writes": 0, "resolvable_write_col_edges": 36936, 
+"transitive_col_edges": 4180, "qualify_failed_statements": 9, 
+"tool_version_stale": false, "indexed_tool_version": "1.34.4", 
+"running_tool_version": "1.34.4"}}

{sql_code_graph-1.34.4 → sql_code_graph-1.35.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sql-code-graph"
-version = "1.34.4"
+version = "1.35.1"
 description = "SQL code graph analyzer and lineage tracer"
 readme = "README.md"
 requires-python = ">=3.12"

{sql_code_graph-1.34.4 → sql_code_graph-1.35.1}/src/sqlcg/__init__.py

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

sql_code_graph-1.35.1/src/sqlcg/cli/commands/viz.py

@@ -0,0 +1,102 @@
+"""The sqlcg viz command — generate a self-contained graph-explorer HTML.
+
+Plan: plan/sprints/feature_graph_viz.md §"CLI signature".
+
+Queries the live graph (via the server-aware ``run_read_routed`` seam),
+attaches per-table label facets (tags/jobs) from BYO CSVs, and writes ONE
+self-contained ``.html`` with the force-graph library inlined — openable on
+Windows via ``file://``. Touches no parser/indexer/lineage code.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from sqlcg.core.config import get_viz_schemas
+from sqlcg.utils.logging import getLogger
+from sqlcg.viz.data import build_viz_data
+from sqlcg.viz.render import DEFAULT_VIZ_OUT, render_html
+from sqlcg.viz.tags import FacetMap, load_facet, resolve_labels
+
+logger = getLogger(__name__)
+console = Console()
+
+
+def _facet_payload(facet: FacetMap) -> dict:
+    """Shape a FacetMap for baking: ``{labels, colors}``."""
+    return {"labels": facet.labels, "colors": facet.colors}
+
+
+def viz_cmd(
+    tags: Path | None = typer.Option(  # noqa: B008
+        None,
+        "--tags",
+        help=(
+            "BYO tags CSV (pattern,label[,color]; header required). The 'tag' "
+            "facet drives the legend swatches (color + filter). Patterns are "
+            "fnmatch globs (*, ?, [seq]) matched case-insensitively against the "
+            "qualified table name. Many-to-many. Omit to hide the tag legend."
+        ),
+    ),
+    jobs: Path | None = typer.Option(  # noqa: B008
+        None,
+        "--jobs",
+        help=(
+            "BYO jobs CSV, same shape as --tags. The 'job' facet drives the job "
+            "dropdown (filter only). Omit to leave the dropdown empty."
+        ),
+    ),
+    out: Path | None = typer.Option(  # noqa: B008
+        None,
+        "--out",
+        help=f"Output HTML path (default: {DEFAULT_VIZ_OUT} in the current directory).",
+    ),
+    config_dir: Path = typer.Option(  # noqa: B008
+        Path("."),
+        "--config-dir",
+        help="Directory searched for .sqlcg.toml ([sqlcg.viz] schemas).",
+    ),
+) -> None:
+    """Generate a self-contained graph-explorer HTML from the live graph.
+
+    Reads the graph via the server-aware routed-read path (never a direct DB
+    open). The emitted file inlines the force-graph library plus the baked node/
+    edge/adjacency data and the tag/job facets — no external resources — so it
+    opens by double-click on Windows.
+
+    The client-side filter composes schema ∩ kind ∩ tag (multi-select per facet,
+    union within a facet, intersection across) plus a job dropdown; an edge
+    renders only when both endpoints are visible. Node kinds table/view/temp are
+    ON by default, cte/derived OFF (switchable).
+    """
+    out_path = out if out is not None else Path(DEFAULT_VIZ_OUT)
+
+    schemas = get_viz_schemas(config_dir)
+
+    data = build_viz_data()
+
+    tag_facet = load_facet(tags, "tag") if tags is not None else FacetMap(name="tag")
+    job_facet = load_facet(jobs, "job") if jobs is not None else FacetMap(name="job")
+
+    # Attach resolved facet labels to every node (m2m glob resolution).
+    for node in data["nodes"]:
+        node["tags"] = resolve_labels(node["id"], tag_facet)
+        node["jobs"] = resolve_labels(node["id"], job_facet)
+
+    html = render_html(
+        data,
+        _facet_payload(tag_facet),
+        _facet_payload(job_facet),
+        schemas,
+    )
+    out_path.write_text(html, encoding="utf-8")
+
+    schema_count = len(schemas) if schemas else len({n["schema"] for n in data["nodes"]})
+    console.print(
+        f"Wrote {out_path} — {len(data['nodes'])} nodes, "
+        f"{len(data['links'])} edges, {len(tag_facet.labels)} tags, "
+        f"{len(job_facet.labels)} jobs, {schema_count} schemas."
+    )

{sql_code_graph-1.34.4 → sql_code_graph-1.35.1}/src/sqlcg/cli/main.py

@@ -16,6 +16,7 @@ from sqlcg.cli.commands import (
     reindex,
     report,
     uninstall,
+    viz,
     watch,
 )
 
@@ -84,6 +85,7 @@ app.command("reindex")(reindex.reindex_cmd)
 app.command("watch")(watch.watch_cmd)
 app.command("gain")(gain.gain_cmd)
 app.command("report")(report.report_cmd)
+app.command("viz")(viz.viz_cmd)
 app.command("install")(install.install_cmd)
 app.command("uninstall")(uninstall.uninstall_cmd)
 

{sql_code_graph-1.34.4 → sql_code_graph-1.35.1}/src/sqlcg/core/config.py

@@ -151,6 +151,44 @@ def get_noise_filter_patterns(path: Path) -> list[str]:
     return default_patterns
 
 
+def get_viz_schemas(path: Path) -> list[str]:
+    """Get the curated viz schema list from .sqlcg.toml.
+
+    Reads [sqlcg.viz] -> schemas (a list of schema-name strings) from
+    .sqlcg.toml. Used by ``sqlcg viz`` to decide which schemas get a distinct
+    hue / appear as multi-select facets. When the block/key is absent or not a
+    list, returns ``[]`` and the generator falls back to **data-derived**
+    schemas (every distinct schema present in the graph), preserving the
+    zero-config small-repo path::
+
+        [sqlcg.viz]
+        schemas = ["ba", "da", "ia_analytics"]
+
+    This reader mirrors ``get_schema_aliases`` / ``get_noise_filter_patterns``
+    exactly (same .sqlcg.toml open, same ``except Exception: pass`` guard, same
+    fallback shape). It is presentation-only config; it never touches indexing
+    or lineage.
+
+    Args:
+        path: Root directory to search for .sqlcg.toml
+
+    Returns:
+        List of configured schema names. ``[]`` when the key is absent or
+        malformed (caller derives schemas from the data).
+    """
+    config_file = Path(path) / ".sqlcg.toml"
+    if config_file.exists():
+        try:
+            with open(config_file, "rb") as f:
+                config = tomllib.load(f)
+            raw = config.get("sqlcg", {}).get("viz", {}).get("schemas")
+            if isinstance(raw, list):
+                return [s for s in raw if isinstance(s, str)]
+        except Exception:
+            pass
+    return []
+
+
 def get_ignored_tables(path: Path) -> list[str]:
     """Get explicitly-ignored qualified table names from .sqlcg.toml.
 

{sql_code_graph-1.34.4 → sql_code_graph-1.35.1}/src/sqlcg/parsers/ansi_parser.py

@@ -551,25 +551,44 @@ class AnsiParser(SqlParser):
         # measurement artifact (96.1%/4,544 of 4,727 on the DWH corpus).
         can_have_lineage = self._can_have_column_lineage(stmt)
 
+        # Phantom source-node gate (#161): a non-table/non-view CREATE
+        # (SEQUENCE / STAGE / FILE FORMAT / SCHEMA / INDEX / PROCEDURE / ...) has
+        # target=None and no data-flow source. Its only Table node is its own
+        # object name, which _fallback_table_scan below would otherwise scoop into
+        # `sources`, leaking a phantom SqlTable SOURCE node + SELECTS_FROM edge
+        # into the graph. #159 fixed the kind LABEL (-> OTHER); this closes the
+        # source-node half. Keying off stmt.kind (the sqlglot AST value, e.g.
+        # 'SEQUENCE') keeps the gate independent of the _classify/QueryKind path.
+        # CREATE TABLE/VIEW ... AS SELECT keep kind in (TABLE, VIEW) and so retain
+        # their real sources. Real procedure lineage comes from the spliced inner
+        # DML (a separate node the gate never touches), so gating PROCEDURE is
+        # edge-neutral. This single gate feeds all three
+        # `referenced_tables.extend(query_node.sources)` sites
+        # (ansi_parser.py:246, snowflake_parser.py:784 / :944).
+        is_non_table_create = isinstance(stmt, exp.Create) and stmt.kind not in ("TABLE", "VIEW")
+
         # Try to extract table references using scope analysis
         try:
-            # Use pre-built scope if provided, otherwise build it here (fallback)
-            root_scope = scope
-            if root_scope is None:
-                from sqlglot.optimizer.scope import build_scope
-
-                root_scope = build_scope(stmt)
-
-            if root_scope:
-                sources = self._real_tables(root_scope)
+            if is_non_table_create:
+                sources = []
             else:
-                # Fallback to basic table extraction
-                sources = [
-                    r
-                    for s in self._fallback_table_scan(stmt)
-                    if (r := self._apply_table_alias(s)) is not None
-                ]
-                parse_failed = can_have_lineage
+                # Use pre-built scope if provided, otherwise build it here (fallback)
+                root_scope = scope
+                if root_scope is None:
+                    from sqlglot.optimizer.scope import build_scope
+
+                    root_scope = build_scope(stmt)
+
+                if root_scope:
+                    sources = self._real_tables(root_scope)
+                else:
+                    # Fallback to basic table extraction
+                    sources = [
+                        r
+                        for s in self._fallback_table_scan(stmt)
+                        if (r := self._apply_table_alias(s)) is not None
+                    ]
+                    parse_failed = can_have_lineage
         except Exception as exc:
             logger.debug("Failed to build scope for statement %d in %s: %s", stmt_index, path, exc)
             sources = [

sql_code_graph-1.35.1/src/sqlcg/viz/__init__.py

@@ -0,0 +1,10 @@
+"""Self-contained graph-visualization generator for ``sqlcg viz``.
+
+Plan: plan/sprints/feature_graph_viz.md
+
+A pure read + render feature: queries the live DuckDB graph (via the
+server-aware ``run_read_routed`` seam), resolves query-anchored edges to
+table->table links, attaches per-table label facets (tags/jobs) from a BYO
+CSV, and emits ONE self-contained HTML file with the force-graph library
+inlined. No parser/indexer/lineage code is touched.
+"""