sql-diff-explainer 0.1.2__py3-none-any.whl → 0.1.3__py3-none-any.whl

sql_diff_explainer/__init__.py

@@ -4,23 +4,32 @@ from .core import (
     SQLChange,
     SQLDiffError,
     SQLDiffResult,
+    SQLDirectoryDiffResult,
+    SQLFileDiff,
     SqlglotParser,
     SQLParseError,
     SQLParser,
     UnsupportedSQL,
+    compare_sql_directories,
     explain_diff,
     explain_sql_change,
 )
+from .reports import render_html_report, to_sarif
 
 __all__ = [
     "SQLChange",
+    "SQLDirectoryDiffResult",
     "SQLDiffError",
     "SQLDiffResult",
+    "SQLFileDiff",
     "SQLParseError",
     "SQLParser",
     "SqlglotParser",
     "UnsupportedSQL",
+    "compare_sql_directories",
     "explain_diff",
     "explain_sql_change",
+    "render_html_report",
+    "to_sarif",
 ]
-__version__ = "0.1.2"
+__version__ = "0.1.3"

sql_diff_explainer/cli.py

@@ -5,7 +5,14 @@ import json
 import sys
 from pathlib import Path
 
-from .core import SQLDiffError, explain_sql_change
+from .core import (
+    SQLDiffError,
+    SQLDiffResult,
+    SQLDirectoryDiffResult,
+    compare_sql_directories,
+    explain_sql_change,
+)
+from .reports import render_html_report, to_sarif
 
 _RISK_SEVERITY = {"low": 0, "medium": 1, "high": 2}
 
@@ -13,12 +20,25 @@ _RISK_SEVERITY = {"low": 0, "medium": 1, "high": 2}
 def main() -> int:
     """Run the command-line interface."""
     parser = argparse.ArgumentParser(
-        description="Explain structural differences between two SQL files."
+        description="Explain structural differences between SQL files or directories."
+    )
+    parser.add_argument("before", type=Path, nargs="?", help="Original SQL file")
+    parser.add_argument("after", type=Path, nargs="?", help="Updated SQL file")
+    parser.add_argument(
+        "--compare-dirs",
+        nargs=2,
+        type=Path,
+        metavar=("BEFORE_DIR", "AFTER_DIR"),
+        help="Recursively compare matching .sql files in two directories",
     )
-    parser.add_argument("before", type=Path, help="Original SQL file")
-    parser.add_argument("after", type=Path, help="Updated SQL file")
     parser.add_argument("--dialect", help="sqlglot dialect used to parse both files")
-    parser.add_argument("--format", choices=("text", "json"), default="text", dest="output_format")
+    parser.add_argument(
+        "--format",
+        choices=("text", "json", "sarif", "html"),
+        default="text",
+        dest="output_format",
+    )
+    parser.add_argument("--output", type=Path, help="Write the report to this file")
     parser.add_argument(
         "--fail-on-risk",
         choices=tuple(_RISK_SEVERITY),
@@ -26,30 +46,77 @@ def main() -> int:
     )
     args = parser.parse_args()
 
+    directory_mode = args.compare_dirs is not None
+    if directory_mode and (args.before is not None or args.after is not None):
+        parser.error("Use either --compare-dirs or the two SQL file arguments, not both")
+    if not directory_mode and (args.before is None or args.after is None):
+        parser.error("Provide two SQL files or use --compare-dirs BEFORE_DIR AFTER_DIR")
+
     try:
-        result = explain_sql_change(
-            args.before.read_text(encoding="utf-8"),
-            args.after.read_text(encoding="utf-8"),
-            dialect=args.dialect,
-        )
-    except (OSError, SQLDiffError) as exc:
+        if directory_mode:
+            result: SQLDiffResult | SQLDirectoryDiffResult = compare_sql_directories(
+                args.compare_dirs[0],
+                args.compare_dirs[1],
+                dialect=args.dialect,
+            )
+            report_path = ""
+        else:
+            result = explain_sql_change(
+                args.before.read_text(encoding="utf-8"),
+                args.after.read_text(encoding="utf-8"),
+                dialect=args.dialect,
+            )
+            report_path = args.after.as_posix()
+    except (OSError, UnicodeDecodeError, SQLDiffError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
+
     if args.output_format == "json":
-        print(json.dumps(result.to_dict(), indent=2))
+        report = json.dumps(result.to_dict(), indent=2)
+    elif args.output_format == "sarif":
+        report = json.dumps(to_sarif(result, path=report_path or "after.sql"), indent=2)
+    elif args.output_format == "html":
+        report = render_html_report(result, path=report_path or "after.sql")
     else:
-        print(result.summary)
-        if result.risk_reasons:
-            print(f"Risk: {result.risk.upper()} - {' '.join(result.risk_reasons)}")
-        for change in result.changes:
-            print(f"- [{change.risk.upper()}] {change.description}")
-            if change.before is not None:
-                print(f"  before: {change.before}")
-            if change.after is not None:
-                print(f"  after:  {change.after}")
+        lines = [result.summary]
+        if isinstance(result, SQLDiffResult):
+            if result.risk_reasons:
+                lines.append(f"Risk: {result.risk.upper()} - {' '.join(result.risk_reasons)}")
+            file_results = [("", result)]
+        else:
+            file_results = [(item.path, item.result) for item in result.files]
+            lines.extend(f"Removed SQL file: {path}" for path in result.unmatched_before)
+            lines.extend(f"Added SQL file: {path}" for path in result.unmatched_after)
+        for file_path, file_result in file_results:
+            if file_path and file_result.changes:
+                lines.append(f"{file_path}:")
+            for change in file_result.changes:
+                lines.append(f"- [{change.risk.upper()}] {change.description}")
+                if change.before is not None:
+                    lines.append(f"  before: {change.before}")
+                if change.after is not None:
+                    lines.append(f"  after:  {change.after}")
+        report = "\n".join(lines)
+
+    try:
+        if args.output is None:
+            print(report)
+        else:
+            output_text = report if report.endswith("\n") else report + "\n"
+            args.output.write_text(output_text, encoding="utf-8")
+    except OSError as exc:
+        print(f"error: Unable to write report: {exc}", file=sys.stderr)
+        return 2
+
+    has_changes = (
+        bool(result.changes)
+        if isinstance(result, SQLDiffResult)
+        else any(item.result.changes for item in result.files)
+        or bool(result.unmatched_before or result.unmatched_after)
+    )
     if (
         args.fail_on_risk is not None
-        and result.changes
+        and has_changes
         and _RISK_SEVERITY[result.risk] >= _RISK_SEVERITY[args.fail_on_risk]
     ):
         return 1

sql_diff_explainer/core.py

@@ -6,6 +6,7 @@ from abc import ABC, abstractmethod
 from collections import Counter
 from dataclasses import dataclass, field
 from difflib import unified_diff
+from pathlib import Path
 from typing import Any
 
 
@@ -103,6 +104,63 @@ class SQLDiffResult:
         }
 
 
+@dataclass(frozen=True)
+class SQLFileDiff:
+    """The semantic comparison for one matched relative SQL file path."""
+
+    path: str
+    result: SQLDiffResult
+
+    def to_dict(self) -> dict[str, object]:
+        return {"path": self.path, **self.result.to_dict()}
+
+
+@dataclass
+class SQLDirectoryDiffResult:
+    """Comparisons and unmatched SQL files from two directory trees."""
+
+    files: list[SQLFileDiff] = field(default_factory=list)
+    unmatched_before: list[str] = field(default_factory=list)
+    unmatched_after: list[str] = field(default_factory=list)
+
+    @property
+    def risk(self) -> str:
+        """Return the highest file risk; whole-file additions/removals are high risk."""
+        if self.unmatched_before or self.unmatched_after:
+            return "high"
+        severity = {"low": 0, "medium": 1, "high": 2}
+        return max(
+            (item.result.risk for item in self.files),
+            key=severity.__getitem__,
+            default="low",
+        )
+
+    @property
+    def risk_level(self) -> str:
+        return self.risk
+
+    @property
+    def summary(self) -> str:
+        changed = sum(bool(item.result.changes) for item in self.files)
+        unmatched = len(self.unmatched_before) + len(self.unmatched_after)
+        if not changed and not unmatched:
+            return f"No structural SQL changes detected across {len(self.files)} file(s)."
+        return (
+            f"{changed} changed SQL file(s), {unmatched} unmatched SQL file(s); "
+            f"overall risk is {self.risk}."
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "summary": self.summary,
+            "risk": self.risk,
+            "risk_level": self.risk_level,
+            "files": [item.to_dict() for item in self.files],
+            "unmatched_before": list(self.unmatched_before),
+            "unmatched_after": list(self.unmatched_after),
+        }
+
+
 def _sql(node: Any, dialect: str | None) -> str | None:
     if node is None:
         return None
@@ -347,6 +405,62 @@ def explain_sql_change(
     return SQLDiffResult(changes=changes, risk=overall, risk_reasons=reasons, dialect=dialect)
 
 
+def compare_sql_directories(
+    before_dir: str | Path,
+    after_dir: str | Path,
+    *,
+    dialect: str | None = None,
+    parser: SQLParser | None = None,
+) -> SQLDirectoryDiffResult:
+    """Compare recursively discovered SQL files paired by exact relative path.
+
+    Files present on only one side are returned as unmatched instead of being
+    parsed as empty SQL. An unmatched file makes the aggregate risk high.
+    """
+    before_root = Path(before_dir)
+    after_root = Path(after_dir)
+    for label, root in (("before", before_root), ("after", after_root)):
+        if not root.exists():
+            raise SQLDiffError(f"{label} directory does not exist: {root}")
+        if not root.is_dir():
+            raise SQLDiffError(f"{label} path is not a directory: {root}")
+
+    def discover(root: Path) -> dict[str, Path]:
+        return {
+            path.relative_to(root).as_posix(): path
+            for path in sorted(root.rglob("*"))
+            if path.is_file() and path.suffix.lower() == ".sql"
+        }
+
+    before_files = discover(before_root)
+    after_files = discover(after_root)
+    before_paths = set(before_files)
+    after_paths = set(after_files)
+    shared_paths = sorted(before_paths & after_paths)
+    try:
+        comparisons = [
+            SQLFileDiff(
+                path=relative_path,
+                result=explain_sql_change(
+                    before_files[relative_path].read_text(encoding="utf-8"),
+                    after_files[relative_path].read_text(encoding="utf-8"),
+                    dialect=dialect,
+                    parser=parser,
+                ),
+            )
+            for relative_path in shared_paths
+        ]
+    except UnicodeDecodeError as exc:
+        raise SQLDiffError(f"Unable to read SQL file as UTF-8: {exc}") from exc
+    except OSError as exc:
+        raise SQLDiffError(f"Unable to read SQL file: {exc}") from exc
+    return SQLDirectoryDiffResult(
+        files=comparisons,
+        unmatched_before=sorted(before_paths - after_paths),
+        unmatched_after=sorted(after_paths - before_paths),
+    )
+
+
 def explain_diff(before: str, after: str) -> str:
     """Return a readable unified diff for two SQL documents."""
     lines = unified_diff(

sql_diff_explainer/reports.py

@@ -0,0 +1,198 @@
+"""Machine-readable and standalone HTML reports for SQL comparisons."""
+
+from __future__ import annotations
+
+from html import escape
+from pathlib import Path
+from urllib.parse import quote
+
+from .core import SQLDiffResult, SQLDirectoryDiffResult
+
+_SARIF_LEVEL = {"low": "note", "medium": "warning", "high": "error"}
+_SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+
+
+def _artifact_uri(path: str) -> str:
+    candidate = Path(path)
+    if candidate.is_absolute():
+        return candidate.as_uri()
+    return quote(candidate.as_posix(), safe="/-._~")
+
+
+def _sarif_result(
+    *,
+    rule_id: str,
+    risk: str,
+    message: str,
+    path: str,
+    properties: dict[str, object] | None = None,
+) -> dict[str, object]:
+    result: dict[str, object] = {
+        "ruleId": rule_id,
+        "level": _SARIF_LEVEL[risk],
+        "message": {"text": message},
+        "locations": [
+            {
+                "physicalLocation": {
+                    "artifactLocation": {"uri": _artifact_uri(path)},
+                }
+            }
+        ],
+        "properties": {"risk": risk, **(properties or {})},
+    }
+    return result
+
+
+def to_sarif(
+    result: SQLDiffResult | SQLDirectoryDiffResult,
+    *,
+    path: str = "after.sql",
+) -> dict[str, object]:
+    """Convert a single-file or directory comparison to a SARIF 2.1.0 document."""
+    sarif_results: list[dict[str, object]] = []
+    rules: dict[str, dict[str, object]] = {}
+
+    def add_rule(rule_id: str, name: str, description: str) -> None:
+        rules.setdefault(
+            rule_id,
+            {
+                "id": rule_id,
+                "name": name,
+                "shortDescription": {"text": description},
+            },
+        )
+
+    def add_changes(sql_result: SQLDiffResult, file_path: str) -> None:
+        for change in sql_result.changes:
+            rule_id = f"sql-diff-{change.category.replace('_', '-')}"
+            add_rule(rule_id, change.category, f"SQL {change.category.replace('_', ' ')} change")
+            message = change.description
+            if change.before is not None:
+                message += f" Before: {change.before}"
+            if change.after is not None:
+                message += f" After: {change.after}"
+            sarif_results.append(
+                _sarif_result(
+                    rule_id=rule_id,
+                    risk=change.risk,
+                    message=message,
+                    path=file_path,
+                    properties={
+                        "category": change.category,
+                        "before": change.before,
+                        "after": change.after,
+                    },
+                )
+            )
+
+    if isinstance(result, SQLDiffResult):
+        add_changes(result, path)
+    else:
+        for file_diff in result.files:
+            add_changes(file_diff.result, file_diff.path)
+        for unmatched, rule_id, action in (
+            (result.unmatched_before, "sql-file-removed", "removed"),
+            (result.unmatched_after, "sql-file-added", "added"),
+        ):
+            if unmatched:
+                add_rule(rule_id, f"SQL file {action}", f"SQL file {action} between directories")
+            for file_path in unmatched:
+                sarif_results.append(
+                    _sarif_result(
+                        rule_id=rule_id,
+                        risk="high",
+                        message=f"SQL file {action}: {file_path}",
+                        path=file_path,
+                        properties={"change": action},
+                    )
+                )
+
+    return {
+        "$schema": _SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "SQL Diff Explainer",
+                        "rules": list(rules.values()),
+                    }
+                },
+                "results": sarif_results,
+            }
+        ],
+    }
+
+
+def render_html_report(
+    result: SQLDiffResult | SQLDirectoryDiffResult,
+    *,
+    path: str = "after.sql",
+) -> str:
+    """Render a self-contained HTML report, escaping all SQL and path content."""
+    rows: list[str] = []
+
+    def add_changes(sql_result: SQLDiffResult, file_path: str) -> None:
+        for change in sql_result.changes:
+            rows.append(
+                "<tr>"
+                f"<td>{escape(file_path, quote=True)}</td>"
+                f'<td class="{escape(change.risk, quote=True)}">{escape(change.risk.upper())}</td>'
+                f"<td>{escape(change.description, quote=True)}</td>"
+                f"<td><pre>{escape(change.before or '', quote=True)}</pre></td>"
+                f"<td><pre>{escape(change.after or '', quote=True)}</pre></td>"
+                "</tr>"
+            )
+
+    if isinstance(result, SQLDiffResult):
+        risk = result.risk
+        summary = result.summary
+        add_changes(result, path)
+    else:
+        risk = result.risk
+        summary = result.summary
+        for file_diff in result.files:
+            add_changes(file_diff.result, file_diff.path)
+        for file_path in result.unmatched_before:
+            rows.append(
+                "<tr>"
+                f"<td>{escape(file_path, quote=True)}</td>"
+                '<td class="high">HIGH</td>'
+                "<td>SQL file removed.</td><td><pre>Present before</pre></td>"
+                "<td><pre></pre></td></tr>"
+            )
+        for file_path in result.unmatched_after:
+            rows.append(
+                "<tr>"
+                f"<td>{escape(file_path, quote=True)}</td>"
+                '<td class="high">HIGH</td>'
+                "<td>SQL file added.</td><td><pre></pre></td>"
+                "<td><pre>Present after</pre></td></tr>"
+            )
+
+    if not rows:
+        rows.append('<tr><td colspan="5">No structural SQL changes detected.</td></tr>')
+    return "\n".join(
+        [
+            "<!doctype html>",
+            '<html lang="en"><head><meta charset="utf-8">',
+            '<meta name="viewport" content="width=device-width, initial-scale=1">',
+            "<title>SQL Diff Explainer report</title>",
+            "<style>",
+            "body{font:15px system-ui,sans-serif;margin:2rem;color:#24292f}"
+            "table{border-collapse:collapse;width:100%}th,td{border:1px solid #d0d7de;"
+            "padding:.6rem;text-align:left;vertical-align:top}pre{white-space:pre-wrap;"
+            "overflow-wrap:anywhere;margin:0}.high{color:#cf222e}.medium{color:#9a6700}"
+            ".low{color:#1a7f37}",
+            "</style></head><body>",
+            "<h1>SQL Diff Explainer</h1>",
+            f'<p class="{escape(risk, quote=True)}">Overall risk: '
+            f"{escape(risk.upper(), quote=True)}</p>",
+            f"<p>{escape(summary, quote=True)}</p>",
+            "<table><thead><tr><th>File</th><th>Risk</th><th>Change</th>"
+            "<th>Before</th><th>After</th></tr></thead><tbody>",
+            *rows,
+            "</tbody></table></body></html>",
+            "",
+        ]
+    )

sql_diff_explainer-0.1.3.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.5
+Name: sql-diff-explainer
+Version: 0.1.3
+Summary: Explain SQL schema and migration differences
+Author: zmodz1010
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: sqlglot>=25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SQL Diff Explainer
+
+**See what changed in a SQL query—and why it might matter.**
+
+SQL Diff Explainer compares the structure of two `SELECT` queries and returns
+the changes with a static risk signal, so reviews focus on query behavior rather
+than formatting.
+
+[![PyPI version](https://img.shields.io/pypi/v/sql-diff-explainer)](https://pypi.org/project/sql-diff-explainer/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/sql-diff-explainer/)
+[![License: MIT](https://img.shields.io/pypi/l/sql-diff-explainer)](LICENSE)
+
+## Contents
+
+- [Quick start](#quick-start)
+- [Command-line usage](#command-line-usage)
+- [Directory comparison](#directory-comparison)
+- [SARIF and HTML reports](#sarif-and-html-reports)
+- [What it compares](#what-it-compares)
+- [Use cases](#use-cases)
+- [Scope and limitations](#scope-and-limitations)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Quick start
+
+Install the latest release from [PyPI](https://pypi.org/project/sql-diff-explainer/):
+
+```console
+python -m pip install sql-diff-explainer
+```
+
+Compare two queries from Python:
+
+```python
+from sql_diff_explainer import explain_sql_change
+
+before = """
+SELECT c.customer_id, c.segment, o.order_id
+FROM customers AS c
+LEFT JOIN orders AS o ON c.customer_id = o.customer_id
+"""
+after = """
+SELECT c.customer_id, c.segment, o.order_id
+FROM customers AS c
+INNER JOIN orders AS o ON c.customer_id = o.customer_id
+"""
+
+result = explain_sql_change(before, after)
+print(result.summary)
+for change in result.changes:
+    print(
+        f"{change.category}: {change.before} -> {change.after} "
+        f"({change.risk} risk)"
+    )
+```
+
+Output:
+
+```text
+1 SQL change(s) detected; overall risk is high.
+join: LEFT JOIN orders AS o ON c.customer_id = o.customer_id -> INNER JOIN orders AS o ON c.customer_id = o.customer_id (high risk)
+```
+
+The change is classified as high risk because an `INNER JOIN` excludes
+customers without a matching order, whereas a `LEFT JOIN` retains them. The
+result is structured: inspect `result.risk_level` and `result.changes`, or call
+`result.to_dict()` for JSON-ready data. Pass `dialect="postgres"` (or another
+[sqlglot dialect](https://sqlglot.com/sqlglot/dialects.html)) for
+dialect-specific SQL. Invalid SQL raises `SQLParseError`; non-`SELECT` input
+raises `UnsupportedSQL`.
+
+## Command-line usage
+
+The CLI compares two SQL files and prints a human-readable report by default:
+
+```console
+sql-diff-explainer examples/join_before.sql examples/join_after.sql
+```
+
+Choose JSON output, set a parsing dialect, or make a risk threshold fail a CI
+step:
+
+```console
+sql-diff-explainer before.sql after.sql --format json
+sql-diff-explainer before.sql after.sql --dialect postgres
+sql-diff-explainer before.sql after.sql --fail-on-risk medium
+```
+
+`--fail-on-risk` accepts `low`, `medium`, or `high`. It exits with status `1`
+when detected changes meet or exceed the threshold; the text or JSON report is
+still printed. No detected changes exit successfully. Input-file errors and
+SQL parse/support errors exit with status `2`.
+
+Try the runnable before/after pairs in [`examples/`](examples/):
+
+```console
+sql-diff-explainer examples/filter_before.sql examples/filter_after.sql --format json
+sql-diff-explainer examples/aggregation_before.sql examples/aggregation_after.sql
+sql-diff-explainer examples/distinct_before.sql examples/distinct_after.sql
+```
+
+### Directory comparison
+
+Compare two directory trees recursively. SQL files are paired by their exact
+relative path (with `/` separators); the `.sql` extension is matched
+case-insensitively. Files present on only one side are reported as additions
+or removals rather than parsed as empty SQL, and raise the aggregate risk to
+high:
+
+```console
+sql-diff-explainer --compare-dirs models/main models/review --format json
+sql-diff-explainer --compare-dirs models/main models/review --fail-on-risk high
+```
+
+The JSON report includes each matched file's ordinary SQL diff, plus
+`unmatched_before` and `unmatched_after` path lists. A missing or non-directory
+input, unreadable file, or invalid SQL exits with status `2`.
+
+The same operation is available in Python:
+
+```python
+from sql_diff_explainer import compare_sql_directories
+
+result = compare_sql_directories("models/main", "models/review")
+print(result.to_dict())
+```
+
+### SARIF and HTML reports
+
+Emit SARIF 2.1.0 results for GitHub code scanning integrations, or generate a
+self-contained HTML report that can be attached to a review:
+
+```console
+sql-diff-explainer before.sql after.sql --format sarif --output sql-diff.sarif
+sql-diff-explainer --compare-dirs models/main models/review --format html --output review.html
+```
+
+Both formats work with the existing `--fail-on-risk` threshold. SARIF maps
+high, medium, and low risk to `error`, `warning`, and `note`; report output is
+still written when the threshold causes exit status `1`. HTML escapes SQL text
+and file paths. Python callers can use `to_sarif(result)` or
+`render_html_report(result)` with either `SQLDiffResult` or
+`SQLDirectoryDiffResult`.
+
+## What it compares
+
+The analyzer compares supported `SELECT` query features and reports additions,
+removals, or changes with a low, medium, or high risk classification:
+
+| Feature | Examples of changes |
+| --- | --- |
+| Projections | Selected columns and expressions |
+| Joins | Join target, predicate, or type |
+| Filters | `WHERE` predicates |
+| Aggregation | Aggregate functions and `GROUP BY` expressions |
+| Ordering and pagination | `ORDER BY`, `LIMIT`, and `OFFSET` |
+| Duplicate handling | `DISTINCT` added or removed |
+
+Join or filter changes can alter which rows qualify; grouping or aggregation
+changes can change a metric's meaning or result grain; and pagination changes
+can affect which rows downstream consumers receive.
+
+## Use cases
+
+- Review dbt models or warehouse SQL in a pull request.
+- Spot join and filter changes that could alter row counts.
+- Check grouping and aggregation changes that could shift metric grain.
+- Add a lightweight risk threshold to a CI check.
+- Explain generated SQL changes without treating formatting-only differences
+  as query changes.
+
+## Scope and limitations
+
+This is static analysis, not a SQL execution engine or correctness proof. It
+does not connect to a database, validate schemas or permissions, estimate query
+plans or cost, inspect table statistics or null rates, or decide whether a
+business metric is correct. It compares supported query structure; it does not
+analyze a multi-statement migration file or guarantee complete semantic
+equivalence across SQL dialects. Risk levels are review signals, not
+predictions. Pair the report with warehouse tests, representative row-count
+checks, query-plan review, and domain-owner input.
+
+## Development
+
+The package requires Python 3.10 or newer and uses a `src/` layout.
+
+```console
+python -m venv .venv
+```
+
+Activate the environment, then install the development dependencies and run
+the checks:
+
+```console
+# macOS / Linux
+source .venv/bin/activate
+
+# Windows PowerShell
+.venv\Scripts\Activate.ps1
+
+python -m pip install -e ".[dev]"
+python -m pytest
+ruff check .
+```
+
+## Contributing
+
+Bug reports, focused improvements, and pull requests are welcome. Please
+include or update tests for behavior changes and keep documentation aligned
+with the supported API.
+
+## License
+
+Distributed under the [MIT License](LICENSE).

sql_diff_explainer-0.1.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+sql_diff_explainer/__init__.py,sha256=_Thcgi2aYlJnnAf1beLKPaVHpbEK9doHILFDliYjUsE,743
+sql_diff_explainer/cli.py,sha256=W654_Apfe4o9nWAGlPDAvJs6nmSQZuu34RIlV0W4spc,4866
+sql_diff_explainer/core.py,sha256=3Qx7vkPZUcKfN_u55ID0Ebr30zHDheE75xggtiYa904,17389
+sql_diff_explainer/reports.py,sha256=jIY9lEa3xnj6Q1xojzB3N0S9t-AUAWzNlvRc4rFDQBo,7228
+sql_diff_explainer-0.1.3.dist-info/METADATA,sha256=GwXOieoenCVZOQ1bkHaBVPmjF_VkR-bs4rZZJWTU06M,7795
+sql_diff_explainer-0.1.3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+sql_diff_explainer-0.1.3.dist-info/entry_points.txt,sha256=Pu2gG46es25JExzGO58plyLEsFedeCUM-TQnUeLpOlI,67
+sql_diff_explainer-0.1.3.dist-info/licenses/LICENSE,sha256=OJ2eEuGmpMxVb7jSmuVgeDcVHCEOMBkZgLgTlnK5mQQ,1087
+sql_diff_explainer-0.1.3.dist-info/RECORD,,

sql_diff_explainer-0.1.2.dist-info/METADATA

@@ -1,147 +0,0 @@
-Metadata-Version: 2.5
-Name: sql-diff-explainer
-Version: 0.1.2
-Summary: Explain SQL schema and migration differences
-Author: zmodz1010
-License: MIT
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: sqlglot>=25.0
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff>=0.6; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# SQL Diff Explainer
-
-Explain the meaningful structural differences between two SQL `SELECT` queries.
-
-The package uses [sqlglot](https://github.com/tobymao/sqlglot) behind an abstract
-parser interface, so callers receive a stable result even if the parser
-implementation changes. It reports changes to projections, joins, filters,
-grouping, aggregation, ordering, pagination, and `DISTINCT`, with a static
-low/medium/high risk classification.
-
-The next patch release is **0.1.2**. It adds the CI-friendly CLI
-`--fail-on-risk` threshold.
-
-## Why use SQL Diff Explainer?
-
-Use it in a pull request, migration review, or CI check when a textual SQL diff
-does not explain the behavioral impact of a query change. It is especially
-useful for data-engineering teams reviewing:
-
-- dbt model changes where a join or filter can change row counts
-- warehouse reports where grouping or aggregation changes the grain
-- incremental pipeline queries where `DISTINCT`, `ORDER BY`, `LIMIT`, or
-  `OFFSET` changes the records consumed downstream
-- generated SQL changes where normalized syntax is easier to compare than
-  formatting or alias changes
-
-The result is a structured object, so a CI integration can fail or annotate a
-review based on `result.risk_level`, inspect `result.changes`, or serialize
-`result.to_dict()` as JSON.
-
-## Real-life data-engineering examples
-
-The `examples/` directory contains runnable before/after pairs. For example:
-
-```powershell
-sql-diff-explainer examples\join_before.sql examples\join_after.sql
-sql-diff-explainer examples\filter_before.sql examples\filter_after.sql --format json
-sql-diff-explainer examples\aggregation_before.sql examples\aggregation_after.sql
-sql-diff-explainer examples\distinct_before.sql examples\distinct_after.sql
-```
-
-These scenarios demonstrate the changes reviewers most often need to discuss:
-
-1. **Outer join to inner join:** changing `LEFT JOIN` to `INNER JOIN` can
-   exclude dimension or fact rows without a match, so the tool reports one
-   semantic join change at high risk.
-2. **Added `WHERE` filter:** adding `WHERE order_status = 'completed'` narrows
-   the population and is reported as a filter change.
-3. **Aggregation or grouping change:** changing `COUNT(*)` to `SUM(revenue)`,
-   or changing the `GROUP BY` grain from customer to customer and day, can
-   change metric meaning and row cardinality.
-4. **`DISTINCT`, ordering, and pagination:** adding `DISTINCT` changes duplicate
-   handling; changing `ORDER BY` changes presentation or deterministic paging;
-   changing `LIMIT`/`OFFSET` changes which rows a downstream consumer receives.
-
-Try the same comparisons from Python:
-
-```python
-from sql_diff_explainer import explain_sql_change
-
-result = explain_sql_change(
-    "SELECT c.id FROM customers c LEFT JOIN orders o ON c.id = o.customer_id",
-    "SELECT c.id FROM customers c INNER JOIN orders o ON c.id = o.customer_id",
-)
-assert result.risk_level == "high"
-for change in result.changes:
-    print(change.category, change.risk, change.description)
-```
-
-## What it catches—and what it cannot know
-
-The analyzer parses both inputs with sqlglot and compares the supported
-`SELECT` structure: projections, joins and join types, `WHERE`, `GROUP BY`,
-aggregate functions, `ORDER BY`, `LIMIT`, `OFFSET`, and `DISTINCT`. It provides
-static risk guidance; it does not execute SQL or connect to a warehouse.
-
-Risk is therefore a useful review signal, not a correctness proof. The tool
-cannot infer table statistics, actual null rates, constraints, query plans,
-cost, freshness, permissions, dialect-specific UDF behavior, or whether a
-business metric is correct. It also does not validate schema availability or
-compare multiple statements in a migration file. Pair its output with
-warehouse tests, representative row-count checks, query-plan review, and
-domain-owner approval.
-
-## Development
-
-This project uses a `src/` layout and requires Python 3.10 or newer.
-
-```powershell
-python -m venv .venv
-.venv\Scripts\Activate.ps1
-python -m pip install -e ".[dev]"
-pytest
-```
-
-## Library usage
-
-```python
-from sql_diff_explainer import explain_sql_change
-
-result = explain_sql_change(
-    "SELECT department, COUNT(*) FROM employees GROUP BY department",
-    "SELECT department, COUNT(*) FROM employees WHERE active = TRUE GROUP BY department",
-)
-print(result.to_dict())
-```
-
-`explain_sql_change` raises `SQLParseError` for invalid SQL and `UnsupportedSQL`
-for non-`SELECT` statements. Pass `dialect="postgres"` (or another sqlglot
-dialect) when parsing dialect-specific syntax.
-
-## CLI
-
-```powershell
-sql-diff-explainer before.sql after.sql
-sql-diff-explainer before.sql after.sql --dialect postgres --format json
-sql-diff-explainer before.sql after.sql --fail-on-risk medium
-sql-diff-explainer before.sql after.sql --format json --fail-on-risk high
-```
-
-`--fail-on-risk` accepts `low`, `medium`, or `high` and exits with status 1 when
-detected overall risk meets or exceeds the chosen threshold. It does not suppress
-the regular text or JSON report. Comparisons with no detected changes exit
-successfully even though their baseline report risk is `low`. JSON output is
-intended for CI and integrations; text output is optimized for human review.
-
-Exit codes:
-
-- `0`: the comparison succeeded and no detected change met the configured
-  threshold (or `--fail-on-risk` was not set).
-- `1`: detected overall risk met or exceeded `--fail-on-risk`.
-- `2`: an input file could not be read or an expected SQL parse/support error
-  occurred.

sql_diff_explainer-0.1.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-sql_diff_explainer/__init__.py,sha256=P-jgWkLNkeuM1kcLChW7rSYWn6EpqOY8K0qMvALxqyA,488
-sql_diff_explainer/cli.py,sha256=XNYIVozEXbjJa_1PXX6ZYmgqxmqHkLHAYNuKaovMCJI,2091
-sql_diff_explainer/core.py,sha256=P9NrPjHGivx-sGlyIyVi7V41x4R2lH3ETC4y8opz_yQ,13265
-sql_diff_explainer-0.1.2.dist-info/METADATA,sha256=0UOgvJOzI3j8gbI64wGVOq1YkGKkNNajipAEGyYJjL4,5863
-sql_diff_explainer-0.1.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-sql_diff_explainer-0.1.2.dist-info/entry_points.txt,sha256=Pu2gG46es25JExzGO58plyLEsFedeCUM-TQnUeLpOlI,67
-sql_diff_explainer-0.1.2.dist-info/licenses/LICENSE,sha256=OJ2eEuGmpMxVb7jSmuVgeDcVHCEOMBkZgLgTlnK5mQQ,1087
-sql_diff_explainer-0.1.2.dist-info/RECORD,,