sql-diff-explainer 0.1.1__tar.gz → 0.1.3__tar.gz

sql_diff_explainer-0.1.3/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,216 @@
+# 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/examples/aggregation_after.sql

@@ -0,0 +1,3 @@
+SELECT customer_id, order_date, SUM(order_total) AS revenue
+FROM orders
+GROUP BY customer_id, order_date;

sql_diff_explainer-0.1.3/examples/aggregation_before.sql

@@ -0,0 +1,3 @@
+SELECT customer_id, COUNT(*) AS order_count
+FROM orders
+GROUP BY customer_id;

sql_diff_explainer-0.1.3/examples/distinct_after.sql

@@ -0,0 +1,4 @@
+SELECT DISTINCT customer_id, event_type
+FROM customer_events
+ORDER BY customer_id, event_type
+LIMIT 50 OFFSET 100;

sql_diff_explainer-0.1.3/examples/distinct_before.sql

@@ -0,0 +1,4 @@
+SELECT customer_id, event_type
+FROM customer_events
+ORDER BY customer_id, event_type
+LIMIT 100;

sql_diff_explainer-0.1.3/examples/filter_after.sql

@@ -0,0 +1,4 @@
+SELECT order_id, customer_id, order_total
+FROM orders
+WHERE order_date >= DATE '2026-01-01'
+  AND order_status = 'completed';

sql_diff_explainer-0.1.3/examples/filter_before.sql

@@ -0,0 +1,3 @@
+SELECT order_id, customer_id, order_total
+FROM orders
+WHERE order_date >= DATE '2026-01-01';

sql_diff_explainer-0.1.3/examples/join_after.sql

@@ -0,0 +1,3 @@
+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;

sql_diff_explainer-0.1.3/examples/join_before.sql

@@ -0,0 +1,3 @@
+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;

{sql_diff_explainer-0.1.1 → sql_diff_explainer-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sql-diff-explainer"
-version = "0.1.1"
+version = "0.1.3"
 description = "Explain SQL schema and migration differences"
 readme = "README.md"
 requires-python = ">=3.10"

{sql_diff_explainer-0.1.1 → sql_diff_explainer-0.1.3}/src/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.1"
+__version__ = "0.1.3"

sql_diff_explainer-0.1.3/src/sql_diff_explainer/cli.py

@@ -0,0 +1,127 @@
+"""Command-line interface for SQL Diff Explainer."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+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}
+
+
+def main() -> int:
+    """Run the command-line interface."""
+    parser = argparse.ArgumentParser(
+        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("--dialect", help="sqlglot dialect used to parse both files")
+    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),
+        help="Exit with status 1 when detected risk meets or exceeds this level",
+    )
+    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:
+        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":
+        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:
+        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 has_changes
+        and _RISK_SEVERITY[result.risk] >= _RISK_SEVERITY[args.fail_on_risk]
+    ):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())