sql-glider 0.1.20__py3-none-any.whl → 0.1.21__py3-none-any.whl

{sql_glider-0.1.20.dist-info → sql_glider-0.1.21.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-glider
-Version: 0.1.20
+Version: 0.1.21
 Summary: SQL Utility Toolkit for better understanding, use, and governance of your queries in a native environment.
 Project-URL: Homepage, https://github.com/rycowhi/sql-glider/
 Project-URL: Repository, https://github.com/rycowhi/sql-glider/
@@ -32,8 +32,12 @@ Description-Content-Type: text/markdown
 
 # SQL Glider
 
+![SQL Glider Logo](./docs/docs/static/sqlglider-logo-transparent.png)
+
 SQL Utility Toolkit for better understanding, use, and governance of your queries in a native environment.
 
+**[Read the docs](https://rycowhi.github.io/sql-glider/)**
+
 ## Overview
 
 SQL Glider provides powerful column-level and table-level lineage analysis for SQL queries using SQLGlot. It operates on standalone SQL files without requiring a full project setup, making it perfect for ad-hoc analysis, data governance, and understanding query dependencies.
@@ -409,6 +413,17 @@ uv run sqlglider graph query graph.json --upstream orders.customer_id
 
 # Query downstream dependencies (find all columns affected by a source)
 uv run sqlglider graph query graph.json --downstream customers.id
+
+# Query with Mermaid diagram output
+uv run sqlglider graph query graph.json --upstream orders.customer_id -f mermaid
+
+# Query with DOT (Graphviz) diagram output
+uv run sqlglider graph query graph.json --downstream customers.id -f dot
+
+# Visualize entire graph as a diagram
+uv run sqlglider graph visualize graph.json                    # Mermaid (default)
+uv run sqlglider graph visualize graph.json -f dot             # DOT/Graphviz
+uv run sqlglider graph visualize graph.json -o lineage.mmd     # Save to file
 ```
 
 **Example Upstream Query Output:**
@@ -796,6 +811,31 @@ src/sqlglider/
     └── file_utils.py         # File I/O utilities
 ```
 
+## Documentation
+
+Project documentation is built with [Zensical](https://zensical.org/) and lives in the `docs/` directory:
+
+```
+docs/
+├── zensical.toml    # Site configuration (name, theme, features)
+└── docs/            # Markdown content
+    └── index.md     # Landing page
+```
+
+To preview docs locally:
+
+```bash
+cd docs && uv run zensical serve
+```
+
+To build the static site:
+
+```bash
+cd docs && uv run zensical build
+```
+
+The built site outputs to `docs/site/` (git-ignored). Documentation is automatically deployed to GitHub Pages on pushes to `main` via the `docs.yml` workflow.
+
 ## Publishing
 
 SQL Glider is configured for publishing to both TestPyPI and PyPI using `uv`.

{sql_glider-0.1.20.dist-info → sql_glider-0.1.21.dist-info}/RECORD

@@ -1,6 +1,6 @@
 sqlglider/__init__.py,sha256=gDf7s52dMcX7JuCZ1SLawcB1vb3U0yJCohu9RQAATBY,125
-sqlglider/_version.py,sha256=P88Jfo9OvOr8LB0vHFqLUwFR7A0eE281KxEewbcCSBc,706
-sqlglider/cli.py,sha256=9zNMaw3rgcqb6uG05VJTYbLUXmZzdX87gAOJ4Zg3xjY,65319
+sqlglider/_version.py,sha256=QwRysHnO-cJwIFSvXReHDj93DEPhlibOTtnnb25J9-c,706
+sqlglider/cli.py,sha256=jQisnNRvRR5AeBnGF7POtcndMR-7cen7yfp7WDShgO4,68523
 sqlglider/global_models.py,sha256=2vyJXAuXOsXQpE-D3F0ejj7eR9z0nDWFjTkielhzM8k,356
 sqlglider/catalog/__init__.py,sha256=2PqFPyzFXJ14FpSUcBmVK2L-a_ypWQHAbHFHxLDk_LE,814
 sqlglider/catalog/base.py,sha256=R7htHC43InpH4uRjYk33dMYYji6oylHns7Ye_mgfjJE,3116
@@ -12,6 +12,7 @@ sqlglider/dissection/formatters.py,sha256=M7gsmTNljRIeLIRv4D0vHvqJVrTqWSpsg7vem8
 sqlglider/dissection/models.py,sha256=RRD3RIteqbUBY6e-74skKDvMH3qeAUaqA2sFcrjP5GQ,3618
 sqlglider/graph/__init__.py,sha256=4DDdrPM75CmeQWt7wHdBsjCm1s70BHGLYdijIbaUEKY,871
 sqlglider/graph/builder.py,sha256=VNBdsDlkiaId3JGvr2G4h6OIFek_9zPsGMIYL9GpJlk,15796
+sqlglider/graph/diagram_formatters.py,sha256=loCpT343Awuj1mue8pv2fNTfwrLfK8n9adlfpPI_OQw,10825
 sqlglider/graph/formatters.py,sha256=p85-WN9oPmEETsAtWSo1sIQELF36w85QoFEJyfBZGoM,4800
 sqlglider/graph/merge.py,sha256=uUZlm4BN3S9gRL66Cc2mzhbtuh4SVAv2n4cN4eUEQBU,4077
 sqlglider/graph/models.py,sha256=EYmjv_WzDSNp_WfhJ6H-qBIOkAcoNKS7GRUryfKrHuY,9330
@@ -31,8 +32,8 @@ sqlglider/utils/__init__.py,sha256=KGp9-UzKz_OFBOTFoSy-g-NXDZsvyWXG_9-1zcC6ePE,2
 sqlglider/utils/config.py,sha256=qx5zE9pjLCCzHQDFVPLVd7LgJ-lghxUa2x-aZOAHByY,4962
 sqlglider/utils/file_utils.py,sha256=5_ff28E0r1R7emZzsOnRuHd-7zIX6873eyr1SuPEr4E,1093
 sqlglider/utils/schema.py,sha256=LiWrYDunXKJdoSlpKmIaIQ2hLSaIN1iQHqkXjMpGzRE,1883
-sql_glider-0.1.20.dist-info/METADATA,sha256=tC3YZY7IuxfVzi7GvYEw_2JAD20rPwfWecg2YHMS3Pg,28446
-sql_glider-0.1.20.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-sql_glider-0.1.20.dist-info/entry_points.txt,sha256=HDuakHqHS5C0HFKsMIxMYmDU7-BLBGrnIJcYaVRu-s0,251
-sql_glider-0.1.20.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-sql_glider-0.1.20.dist-info/RECORD,,
+sql_glider-0.1.21.dist-info/METADATA,sha256=tceZxbt-9yvvLlQn52RcmixUiPs62HhswbJFiGMksmA,29695
+sql_glider-0.1.21.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+sql_glider-0.1.21.dist-info/entry_points.txt,sha256=HDuakHqHS5C0HFKsMIxMYmDU7-BLBGrnIJcYaVRu-s0,251
+sql_glider-0.1.21.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+sql_glider-0.1.21.dist-info/RECORD,,

sqlglider/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.1.20'
-__version_tuple__ = version_tuple = (0, 1, 20)
+__version__ = version = '0.1.21'
+__version_tuple__ = version_tuple = (0, 1, 21)
 
 __commit_id__ = commit_id = None

sqlglider/cli.py

@@ -1642,7 +1642,7 @@ def graph_query(
         "text",
         "--output-format",
         "-f",
-        help="Output format: 'text', 'json', or 'csv'",
+        help="Output format: 'text', 'json', 'csv', 'mermaid', 'mermaid-markdown', or 'dot'",
     ),
 ) -> None:
     """
@@ -1678,10 +1678,10 @@ def graph_query(
         )
         raise typer.Exit(1)
 
-    if output_format not in ["text", "json", "csv"]:
+    if output_format not in ["text", "json", "csv", "mermaid", "mermaid-markdown", "dot"]:
         err_console.print(
             f"[red]Error:[/red] Invalid output format '{output_format}'. "
-            "Use 'text', 'json', or 'csv'."
+            "Use 'text', 'json', 'csv', 'mermaid', 'mermaid-markdown', or 'dot'."
         )
         raise typer.Exit(1)
 
@@ -1699,8 +1699,20 @@ def graph_query(
             _format_query_result_text(result)
         elif output_format == "json":
             _format_query_result_json(result)
-        else:  # csv
+        elif output_format == "csv":
             _format_query_result_csv(result)
+        elif output_format == "mermaid":
+            from sqlglider.graph.diagram_formatters import MermaidFormatter
+
+            print(MermaidFormatter.format_query_result(result))
+        elif output_format == "mermaid-markdown":
+            from sqlglider.graph.diagram_formatters import MermaidMarkdownFormatter
+
+            print(MermaidMarkdownFormatter.format_query_result(result))
+        elif output_format == "dot":
+            from sqlglider.graph.diagram_formatters import DotFormatter
+
+            print(DotFormatter.format_query_result(result))
 
     except FileNotFoundError as e:
         err_console.print(f"[red]Error:[/red] {e}")
@@ -1795,6 +1807,91 @@ def _format_query_result_csv(result) -> None:
         )
 
 
+@graph_app.command("visualize")
+def graph_visualize(
+    graph_file: Path = typer.Argument(
+        ...,
+        exists=True,
+        help="Path to graph JSON file",
+    ),
+    output_format: str = typer.Option(
+        "mermaid",
+        "--output-format",
+        "-f",
+        help="Diagram format: 'mermaid', 'mermaid-markdown', or 'dot'",
+    ),
+    output_file: Optional[Path] = typer.Option(
+        None,
+        "--output-file",
+        "-o",
+        help="Write diagram to file instead of stdout",
+    ),
+) -> None:
+    """
+    Visualize the entire lineage graph as a diagram.
+
+    Generates Mermaid or DOT (Graphviz) diagrams showing all nodes and edges
+    in the graph for visualization tools.
+
+    Examples:
+
+        # Generate Mermaid diagram
+        sqlglider graph visualize graph.json
+
+        # Generate DOT diagram for Graphviz
+        sqlglider graph visualize graph.json -f dot
+
+        # Save to file
+        sqlglider graph visualize graph.json -o lineage.mmd
+
+        # Render DOT to PNG with Graphviz
+        sqlglider graph visualize graph.json -f dot -o lineage.dot
+    """
+    from sqlglider.graph.diagram_formatters import (
+        DotFormatter,
+        MermaidFormatter,
+        MermaidMarkdownFormatter,
+    )
+    from sqlglider.graph.serialization import load_graph
+
+    if output_format not in ["mermaid", "mermaid-markdown", "dot"]:
+        err_console.print(
+            f"[red]Error:[/red] Invalid output format '{output_format}'. "
+            "Use 'mermaid', 'mermaid-markdown', or 'dot'."
+        )
+        raise typer.Exit(1)
+
+    try:
+        graph = load_graph(graph_file)
+
+        if output_format == "mermaid":
+            diagram = MermaidFormatter.format_full_graph(graph)
+        elif output_format == "mermaid-markdown":
+            diagram = MermaidMarkdownFormatter.format_full_graph(graph)
+        else:
+            diagram = DotFormatter.format_full_graph(graph)
+
+        if output_file:
+            output_file.write_text(diagram, encoding="utf-8")
+            console.print(
+                f"[green]Success:[/green] Diagram written to {output_file}"
+            )
+        else:
+            print(diagram)
+
+    except FileNotFoundError as e:
+        err_console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    except ValueError as e:
+        err_console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    except Exception as e:
+        err_console.print(f"[red]Error:[/red] Unexpected error: {e}")
+        raise typer.Exit(1)
+
+
 @app.command()
 def dissect(
     sql_file: Annotated[

sqlglider/graph/diagram_formatters.py

@@ -0,0 +1,330 @@
+"""Diagram formatters for lineage graphs (Mermaid and DOT/Graphviz)."""
+
+import re
+from typing import Set
+
+from sqlglider.graph.models import LineageGraph
+from sqlglider.graph.query import LineageQueryResult
+
+# Color palette (muted jewel tones for light/dark mode compatibility)
+QUERIED_FILL = "#e6a843"
+QUERIED_STROKE = "#b8860b"
+ROOT_FILL = "#4ecdc4"
+ROOT_STROKE = "#2b9e96"
+LEAF_FILL = "#c084fc"
+LEAF_STROKE = "#7c3aed"
+
+
+def _sanitize_mermaid_id(identifier: str) -> str:
+    """Sanitize an identifier for use as a Mermaid node ID.
+
+    Replaces non-alphanumeric characters with underscores.
+
+    Args:
+        identifier: Raw node identifier (e.g., "schema.table.column")
+
+    Returns:
+        Sanitized ID safe for Mermaid syntax
+    """
+    return re.sub(r"[^a-zA-Z0-9_]", "_", identifier)
+
+
+def _quote_dot_id(identifier: str) -> str:
+    """Quote an identifier for use in DOT syntax.
+
+    Args:
+        identifier: Raw node identifier
+
+    Returns:
+        Double-quoted identifier with internal quotes escaped
+    """
+    escaped = identifier.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _collect_query_edges(result: LineageQueryResult) -> Set[tuple[str, str]]:
+    """Extract unique directed edges from all paths in a query result.
+
+    Args:
+        result: Query result containing paths
+
+    Returns:
+        Set of (source, target) identifier pairs
+    """
+    edges: Set[tuple[str, str]] = set()
+    for node in result.related_columns:
+        for path in node.paths:
+            for i in range(len(path.nodes) - 1):
+                edges.add((path.nodes[i], path.nodes[i + 1]))
+    return edges
+
+
+def _collect_query_nodes(result: LineageQueryResult) -> Set[str]:
+    """Extract all unique node identifiers from query result paths.
+
+    Args:
+        result: Query result containing paths
+
+    Returns:
+        Set of node identifiers
+    """
+    nodes: Set[str] = set()
+    for node in result.related_columns:
+        for path in node.paths:
+            nodes.update(path.nodes)
+    # Always include the queried column itself
+    nodes.add(result.query_column)
+    return nodes
+
+
+class MermaidFormatter:
+    """Format lineage graphs and query results as Mermaid diagrams."""
+
+    @staticmethod
+    def format_full_graph(graph: LineageGraph) -> str:
+        """Format complete lineage graph as a Mermaid flowchart.
+
+        Args:
+            graph: LineageGraph with all nodes and edges
+
+        Returns:
+            Mermaid diagram string (flowchart TD syntax)
+        """
+        lines = ["flowchart TD"]
+
+        if not graph.nodes and not graph.edges:
+            return "\n".join(lines)
+
+        # Declare nodes with labels
+        for node in graph.nodes:
+            node_id = _sanitize_mermaid_id(node.identifier)
+            lines.append(f'    {node_id}["{node.identifier}"]')
+
+        # Add edges
+        for edge in graph.edges:
+            src = _sanitize_mermaid_id(edge.source_node)
+            tgt = _sanitize_mermaid_id(edge.target_node)
+            lines.append(f"    {src} --> {tgt}")
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def format_query_result(result: LineageQueryResult) -> str:
+        """Format query result as a Mermaid flowchart with styling.
+
+        The queried column is highlighted in amber, root nodes in teal,
+        and leaf nodes in violet. A legend subgraph is included.
+
+        Args:
+            result: LineageQueryResult from upstream/downstream query
+
+        Returns:
+            Mermaid diagram string with style directives and legend
+        """
+        lines = ["flowchart TD"]
+
+        if not result.related_columns:
+            # Show just the queried node
+            node_id = _sanitize_mermaid_id(result.query_column)
+            lines.append(f'    {node_id}["{result.query_column}"]')
+            return "\n".join(lines)
+
+        all_nodes = _collect_query_nodes(result)
+        edges = _collect_query_edges(result)
+
+        # Declare nodes
+        for identifier in sorted(all_nodes):
+            node_id = _sanitize_mermaid_id(identifier)
+            lines.append(f'    {node_id}["{identifier}"]')
+
+        # Add edges
+        for src, tgt in sorted(edges):
+            lines.append(
+                f"    {_sanitize_mermaid_id(src)} --> {_sanitize_mermaid_id(tgt)}"
+            )
+
+        # Style directives
+        queried_id = _sanitize_mermaid_id(result.query_column)
+        lines.append(
+            f"    style {queried_id} fill:{QUERIED_FILL},stroke:{QUERIED_STROKE},stroke-width:3px"
+        )
+
+        root_ids = set()
+        leaf_ids = set()
+        for node in result.related_columns:
+            if node.is_root:
+                root_ids.add(_sanitize_mermaid_id(node.identifier))
+            if node.is_leaf:
+                leaf_ids.add(_sanitize_mermaid_id(node.identifier))
+
+        for rid in sorted(root_ids):
+            if rid != queried_id:
+                lines.append(f"    style {rid} fill:{ROOT_FILL},stroke:{ROOT_STROKE}")
+
+        for lid in sorted(leaf_ids):
+            if lid != queried_id and lid not in root_ids:
+                lines.append(f"    style {lid} fill:{LEAF_FILL},stroke:{LEAF_STROKE}")
+
+        # Legend
+        lines.append("")
+        lines.append("    subgraph Legend")
+        lines.append('        legend_queried["Queried Column"]')
+        lines.append('        legend_root["Root (no upstream)"]')
+        lines.append('        legend_leaf["Leaf (no downstream)"]')
+        lines.append("    end")
+        lines.append(
+            f"    style legend_queried fill:{QUERIED_FILL},stroke:{QUERIED_STROKE},stroke-width:3px"
+        )
+        lines.append(f"    style legend_root fill:{ROOT_FILL},stroke:{ROOT_STROKE}")
+        lines.append(f"    style legend_leaf fill:{LEAF_FILL},stroke:{LEAF_STROKE}")
+
+        return "\n".join(lines)
+
+
+class MermaidMarkdownFormatter:
+    """Format lineage graphs and query results as Mermaid diagrams wrapped in markdown code fences."""
+
+    @staticmethod
+    def format_full_graph(graph: LineageGraph) -> str:
+        """Format complete lineage graph as a Mermaid diagram in a markdown code block.
+
+        Args:
+            graph: LineageGraph with all nodes and edges
+
+        Returns:
+            Markdown string with fenced Mermaid diagram
+        """
+        mermaid = MermaidFormatter.format_full_graph(graph)
+        return f"```mermaid\n{mermaid}\n```"
+
+    @staticmethod
+    def format_query_result(result: LineageQueryResult) -> str:
+        """Format query result as a Mermaid diagram in a markdown code block.
+
+        Args:
+            result: LineageQueryResult from upstream/downstream query
+
+        Returns:
+            Markdown string with fenced Mermaid diagram
+        """
+        mermaid = MermaidFormatter.format_query_result(result)
+        return f"```mermaid\n{mermaid}\n```"
+
+
+class DotFormatter:
+    """Format lineage graphs and query results as DOT (Graphviz) diagrams."""
+
+    @staticmethod
+    def format_full_graph(graph: LineageGraph) -> str:
+        """Format complete lineage graph as a DOT digraph.
+
+        Args:
+            graph: LineageGraph with all nodes and edges
+
+        Returns:
+            DOT diagram string
+        """
+        lines = [
+            "digraph lineage {",
+            "    rankdir=LR;",
+            "    node [shape=box, style=rounded];",
+        ]
+
+        if not graph.nodes and not graph.edges:
+            lines.append("}")
+            return "\n".join(lines)
+
+        # Declare nodes
+        for node in graph.nodes:
+            lines.append(f"    {_quote_dot_id(node.identifier)};")
+
+        # Add edges
+        for edge in graph.edges:
+            src = _quote_dot_id(edge.source_node)
+            tgt = _quote_dot_id(edge.target_node)
+            lines.append(f"    {src} -> {tgt};")
+
+        lines.append("}")
+        return "\n".join(lines)
+
+    @staticmethod
+    def format_query_result(result: LineageQueryResult) -> str:
+        """Format query result as a DOT digraph with styling.
+
+        The queried column is highlighted in amber, root nodes in teal,
+        and leaf nodes in violet. A legend subgraph is included.
+
+        Args:
+            result: LineageQueryResult from upstream/downstream query
+
+        Returns:
+            DOT diagram string with node attributes and legend
+        """
+        lines = [
+            "digraph lineage {",
+            "    rankdir=LR;",
+            "    node [shape=box, style=rounded];",
+        ]
+
+        if not result.related_columns:
+            qid = _quote_dot_id(result.query_column)
+            lines.append(
+                f'    {qid} [style="rounded,filled", fillcolor="{QUERIED_FILL}"];'
+            )
+            lines.append("}")
+            return "\n".join(lines)
+
+        all_nodes = _collect_query_nodes(result)
+        edges = _collect_query_edges(result)
+
+        # Build styling lookup
+        root_ids: Set[str] = set()
+        leaf_ids: Set[str] = set()
+        for node in result.related_columns:
+            if node.is_root:
+                root_ids.add(node.identifier)
+            if node.is_leaf:
+                leaf_ids.add(node.identifier)
+
+        # Declare nodes with styling
+        for identifier in sorted(all_nodes):
+            qid = _quote_dot_id(identifier)
+            if identifier == result.query_column:
+                lines.append(
+                    f'    {qid} [style="rounded,filled", fillcolor="{QUERIED_FILL}"];'
+                )
+            elif identifier in root_ids:
+                lines.append(
+                    f'    {qid} [style="rounded,filled", fillcolor="{ROOT_FILL}"];'
+                )
+            elif identifier in leaf_ids:
+                lines.append(
+                    f'    {qid} [style="rounded,filled", fillcolor="{LEAF_FILL}"];'
+                )
+            else:
+                lines.append(f"    {qid};")
+
+        # Add edges
+        for src, tgt in sorted(edges):
+            lines.append(f"    {_quote_dot_id(src)} -> {_quote_dot_id(tgt)};")
+
+        # Legend
+        lines.append("")
+        lines.append("    subgraph cluster_legend {")
+        lines.append('        label="Legend";')
+        lines.append("        style=dashed;")
+        lines.append(
+            f'        legend_queried [label="Queried Column", style="rounded,filled", fillcolor="{QUERIED_FILL}"];'
+        )
+        lines.append(
+            f'        legend_root [label="Root (no upstream)", style="rounded,filled", fillcolor="{ROOT_FILL}"];'
+        )
+        lines.append(
+            f'        legend_leaf [label="Leaf (no downstream)", style="rounded,filled", fillcolor="{LEAF_FILL}"];'
+        )
+        lines.append("        legend_queried -> legend_root [style=invis];")
+        lines.append("        legend_root -> legend_leaf [style=invis];")
+        lines.append("    }")
+
+        lines.append("}")
+        return "\n".join(lines)