sql-diff-explainer 0.1.0__tar.gz → 0.1.2__tar.gz

sql_diff_explainer-0.1.2/PKG-INFO

@@ -0,0 +1,147 @@
+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/README.md

@@ -0,0 +1,133 @@
+# 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/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.2/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.2/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.2/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.2/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.2/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.2/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.2/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.0 → sql_diff_explainer-0.1.2}/pyproject.toml

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

{sql_diff_explainer-0.1.0 → sql_diff_explainer-0.1.2}/src/sql_diff_explainer/__init__.py

@@ -23,4 +23,4 @@ __all__ = [
     "explain_diff",
     "explain_sql_change",
 ]
-__version__ = "0.2.0"
+__version__ = "0.1.2"

{sql_diff_explainer-0.1.0 → sql_diff_explainer-0.1.2}/src/sql_diff_explainer/cli.py

@@ -7,6 +7,8 @@ from pathlib import Path
 
 from .core import SQLDiffError, explain_sql_change
 
+_RISK_SEVERITY = {"low": 0, "medium": 1, "high": 2}
+
 
 def main() -> int:
     """Run the command-line interface."""
@@ -17,6 +19,11 @@ def main() -> int:
     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(
+        "--fail-on-risk",
+        choices=tuple(_RISK_SEVERITY),
+        help="Exit with status 1 when detected risk meets or exceeds this level",
+    )
     args = parser.parse_args()
 
     try:
@@ -40,6 +47,12 @@ def main() -> int:
                 print(f"  before: {change.before}")
             if change.after is not None:
                 print(f"  after:  {change.after}")
+    if (
+        args.fail_on_risk is not None
+        and result.changes
+        and _RISK_SEVERITY[result.risk] >= _RISK_SEVERITY[args.fail_on_risk]
+    ):
+        return 1
     return 0
 
 

{sql_diff_explainer-0.1.0 → sql_diff_explainer-0.1.2}/src/sql_diff_explainer/core.py

@@ -81,6 +81,11 @@ class SQLDiffResult:
     risk_reasons: list[str] = field(default_factory=list)
     dialect: str | None = None
 
+    @property
+    def risk_level(self) -> str:
+        """Backward-compatible alias for the overall risk classification."""
+        return self.risk
+
     @property
     def summary(self) -> str:
         if not self.changes:
@@ -91,6 +96,7 @@ class SQLDiffResult:
         return {
             "summary": self.summary,
             "risk": self.risk,
+            "risk_level": self.risk_level,
             "risk_reasons": list(self.risk_reasons),
             "dialect": self.dialect,
             "changes": [change.to_dict() for change in self.changes],
@@ -129,12 +135,24 @@ def _select_expression(tree: Any) -> Any:
     return select
 
 
-def _features(tree: Any, dialect: str | None) -> dict[str, list[str] | str | bool | None]:
+def _join_values(select: Any, dialect: str | None) -> list[tuple[str, str]]:
+    joins = []
+    for join in select.args.get("joins", []):
+        side = (join.args.get("side") or "INNER").upper()
+        target = _sql(join.args.get("this"), dialect) or ""
+        condition = _sql(join.args.get("on"), dialect) or ""
+        joins.append((f"{target} ON {condition}", f"{side} JOIN {target} ON {condition}"))
+    return joins
+
+
+def _features(
+    tree: Any, dialect: str | None
+) -> dict[str, list[str] | list[tuple[str, str]] | str | bool | None]:
     from sqlglot import exp
 
     select = _select_expression(tree)
     projections = [_sql(expression, dialect) or "" for expression in select.expressions]
-    joins = [_sql(join, dialect) or "" for join in select.args.get("joins", [])]
+    joins = _join_values(select, dialect)
     aggregations = sorted(
         {_sql(node, dialect) or "" for node in select.find_all(exp.AggFunc)}
     )
@@ -174,6 +192,10 @@ _RISK = {
     "offset": ("medium", "Changing OFFSET changes which rows are returned."),
     "where": ("medium", "Changing a WHERE predicate changes which rows qualify."),
     "join": ("medium", "Changing a JOIN can change row matching or cardinality."),
+    "join_type": (
+        "high",
+        "Changing an outer JOIN to INNER JOIN can exclude unmatched rows.",
+    ),
 }
 
 
@@ -182,10 +204,11 @@ def _change(
     before: Any,
     after: Any,
     dialect: str | None,
+    risk_key: str | None = None,
 ) -> SQLChange:
     before_text = before if isinstance(before, str) or before is None else _sql(before, dialect)
     after_text = after if isinstance(after, str) or after is None else _sql(after, dialect)
-    key = "removed_" + category if after_text is None else category
+    key = risk_key or ("removed_" + category if after_text is None else category)
     risk = _RISK.get(key, ("medium", f"{category.title()} changed."))[0]
     action = "removed" if after_text is None else "changed" if before_text else "added"
     return SQLChange(
@@ -215,6 +238,48 @@ def _sequence_changes(
     return changes
 
 
+def _join_changes(
+    before: list[tuple[str, str]],
+    after: list[tuple[str, str]],
+    dialect: str | None,
+) -> list[SQLChange]:
+    """Pair joins by target and predicate so join-type changes stay semantic."""
+    before_by_signature = Counter(signature for signature, _ in before)
+    after_by_signature = Counter(signature for signature, _ in after)
+    changes: list[SQLChange] = []
+    for signature in before_by_signature.keys() & after_by_signature.keys():
+        before_rendered = [rendered for item, rendered in before if item == signature]
+        after_rendered = [rendered for item, rendered in after if item == signature]
+        for before_rendered_value, after_rendered_value in zip(
+            before_rendered, after_rendered, strict=True
+        ):
+            if before_rendered_value != after_rendered_value:
+                changes.append(
+                    _change(
+                        "join",
+                        before_rendered_value,
+                        after_rendered_value,
+                        dialect,
+                        risk_key=(
+                            "join_type"
+                            if before_rendered_value.split(" ", 1)[0].upper()
+                            in {"LEFT", "RIGHT", "FULL"}
+                            and after_rendered_value.split(" ", 1)[0].upper() == "INNER"
+                            else None
+                        ),
+                    )
+                )
+    removed = list((before_by_signature - after_by_signature).elements())
+    added = list((after_by_signature - before_by_signature).elements())
+    for signature in removed:
+        rendered = next(rendered for item, rendered in before if item == signature)
+        changes.append(_change("join", rendered, None, dialect))
+    for signature in added:
+        rendered = next(rendered for item, rendered in after if item == signature)
+        changes.append(_change("join", None, rendered, dialect))
+    return changes
+
+
 def explain_sql_change(
     before: str,
     after: str,
@@ -230,7 +295,13 @@ def explain_sql_change(
     after_features = _features(after_tree, dialect)
     changes: list[SQLChange] = []
 
-    sequence_categories = ("select", "joins", "group_by", "aggregation", "order_by")
+    before_joins = before_features["joins"]
+    after_joins = after_features["joins"]
+    if not isinstance(before_joins, list) or not isinstance(after_joins, list):
+        raise UnsupportedSQL("Unable to compare joins")
+    changes.extend(_join_changes(before_joins, after_joins, dialect))
+
+    sequence_categories = ("select", "group_by", "aggregation", "order_by")
     for category in sequence_categories:
         before_values = before_features[category]
         after_values = after_features[category]
@@ -256,8 +327,19 @@ def explain_sql_change(
     for change in changes:
         if severity[change.risk] > severity[overall]:
             overall = change.risk
+        join_type_change = (
+            change.category == "join"
+            and change.before is not None
+            and change.after is not None
+            and change.before.split(" ", 1)[0].upper() in {"LEFT", "RIGHT", "FULL"}
+            and change.after.split(" ", 1)[0].upper() == "INNER"
+        )
         reason = _RISK.get(
-            ("removed_" + change.category if change.after is None else change.category),
+            (
+                "join_type"
+                if join_type_change
+                else ("removed_" + change.category if change.after is None else change.category)
+            ),
             ("medium", ""),
         )[1]
         if reason and reason not in reasons:

sql_diff_explainer-0.1.2/tests/test_core.py

@@ -0,0 +1,204 @@
+import json
+import sys
+
+import pytest
+
+from sql_diff_explainer import SQLParseError, UnsupportedSQL, explain_diff, explain_sql_change
+from sql_diff_explainer.cli import main as cli_main
+
+
+def test_explain_diff_returns_unified_diff() -> None:
+    result = explain_diff("CREATE TABLE users;", "CREATE TABLE accounts;")
+
+    assert "--- before.sql" in result
+    assert "+++ after.sql" in result
+    assert "-CREATE TABLE users;" in result
+    assert "+CREATE TABLE accounts;" in result
+
+
+def test_explain_sql_change_detects_core_query_features() -> None:
+    before = (
+        "SELECT DISTINCT a, COUNT(*) FROM users u WHERE active = 1 "
+        "GROUP BY a ORDER BY a LIMIT 10"
+    )
+    after = (
+        "SELECT a, SUM(amount) FROM users u JOIN orders o ON u.id = o.user_id "
+        "WHERE active = 1 AND region = 'EU' GROUP BY a ORDER BY a DESC LIMIT 20 OFFSET 5"
+    )
+
+    result = explain_sql_change(before, after)
+    categories = {change.category for change in result.changes}
+
+    assert {"select", "join", "aggregation", "distinct", "limit", "offset"}.issubset(categories)
+    assert result.risk == "high"
+    assert result.risk_level == "high"
+    assert result.to_dict()["changes"]
+
+
+def test_explain_sql_change_reports_filter_removal_as_high_risk() -> None:
+    result = explain_sql_change(
+        "SELECT id FROM users WHERE active = TRUE",
+        "SELECT id FROM users",
+    )
+
+    assert result.risk == "high"
+    assert any(change.category == "where" and change.risk == "high" for change in result.changes)
+
+
+def test_explain_sql_change_accepts_dialect() -> None:
+    result = explain_sql_change(
+        "SELECT TOP 5 id FROM users",
+        "SELECT TOP 10 id FROM users",
+        dialect="tsql",
+    )
+
+    assert result.changes[0].category == "limit"
+
+
+def test_parse_and_unsupported_errors_are_clean() -> None:
+    with pytest.raises(SQLParseError):
+        explain_sql_change("SELECT FROM", "SELECT 1")
+    with pytest.raises(UnsupportedSQL):
+        explain_sql_change("CREATE TABLE users (id INT)", "SELECT 1")
+
+
+def test_identical_queries_have_no_changes() -> None:
+    result = explain_sql_change("SELECT id FROM users", "SELECT id FROM users")
+
+    assert result.changes == []
+    assert result.risk == "low"
+
+
+def test_join_type_change_is_one_semantic_change() -> None:
+    result = explain_sql_change(
+        "SELECT users.id FROM users LEFT JOIN orders ON users.id = orders.user_id",
+        "SELECT users.id FROM users INNER JOIN orders ON users.id = orders.user_id",
+    )
+
+    assert len(result.changes) == 1
+    assert result.changes[0].category == "join"
+    assert result.changes[0].risk == "high"
+    assert result.risk_level == "high"
+    assert result.changes[0].before.startswith("LEFT JOIN")
+    assert result.changes[0].after.startswith("INNER JOIN")
+
+
+@pytest.mark.parametrize(
+    ("before", "after", "threshold", "expected_status"),
+    [
+        ("SELECT id FROM users", "SELECT name FROM users", "high", 0),
+        ("SELECT id FROM users", "SELECT name FROM users", "medium", 1),
+        ("SELECT id FROM users", "SELECT name FROM users", "low", 1),
+    ],
+)
+@pytest.mark.parametrize("output_format", ["text", "json"])
+def test_cli_fail_on_risk_thresholds_keep_report_output(
+    tmp_path, monkeypatch, capsys, before, after, threshold, expected_status, output_format
+) -> None:
+    before_path = tmp_path / "before.sql"
+    after_path = tmp_path / "after.sql"
+    before_path.write_text(before, encoding="utf-8")
+    after_path.write_text(after, encoding="utf-8")
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "sql-diff-explainer",
+            str(before_path),
+            str(after_path),
+            "--fail-on-risk",
+            threshold,
+            "--format",
+            output_format,
+        ],
+    )
+
+    assert cli_main() == expected_status
+    stdout = capsys.readouterr().out
+    if output_format == "json":
+        report = json.loads(stdout)
+        assert report["risk"] == "medium"
+        assert report["changes"]
+    else:
+        assert "SQL change(s) detected; overall risk is medium." in stdout
+        assert "Risk: MEDIUM" in stdout
+
+
+@pytest.mark.parametrize("output_format", ["text", "json"])
+def test_cli_fail_on_risk_allows_no_changes(tmp_path, monkeypatch, capsys, output_format) -> None:
+    query = "SELECT id FROM users"
+    before_path = tmp_path / "before.sql"
+    after_path = tmp_path / "after.sql"
+    before_path.write_text(query, encoding="utf-8")
+    after_path.write_text(query, encoding="utf-8")
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "sql-diff-explainer",
+            str(before_path),
+            str(after_path),
+            "--fail-on-risk",
+            "low",
+            "--format",
+            output_format,
+        ],
+    )
+
+    assert cli_main() == 0
+    stdout = capsys.readouterr().out
+    if output_format == "json":
+        report = json.loads(stdout)
+        assert report["risk"] == "low"
+        assert report["changes"] == []
+    else:
+        assert stdout.strip() == "No structural SQL changes detected."
+
+
+def test_cli_fail_on_risk_preserves_sql_error_exit_status(
+    tmp_path, monkeypatch, capsys
+) -> None:
+    before_path = tmp_path / "before.sql"
+    after_path = tmp_path / "after.sql"
+    before_path.write_text("SELECT FROM", encoding="utf-8")
+    after_path.write_text("SELECT id FROM users", encoding="utf-8")
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "sql-diff-explainer",
+            str(before_path),
+            str(after_path),
+            "--fail-on-risk",
+            "low",
+        ],
+    )
+
+    assert cli_main() == 2
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert captured.err.startswith("error: Unable to parse SQL:")
+
+
+def test_cli_fail_on_risk_preserves_unreadable_file_exit_status(
+    tmp_path, monkeypatch, capsys
+) -> None:
+    before_path = tmp_path / "missing.sql"
+    after_path = tmp_path / "after.sql"
+    after_path.write_text("SELECT id FROM users", encoding="utf-8")
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "sql-diff-explainer",
+            str(before_path),
+            str(after_path),
+            "--fail-on-risk",
+            "low",
+        ],
+    )
+
+    assert cli_main() == 2
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert captured.err.startswith("error:")

sql_diff_explainer-0.1.0/PKG-INFO

@@ -1,61 +0,0 @@
-Metadata-Version: 2.5
-Name: sql-diff-explainer
-Version: 0.1.0
-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.
-
-## 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
-```
-
-JSON output is intended for CI and integrations; text output is optimized for
-human review. The process exits with status 2 for unreadable files or expected
-SQL errors.

sql_diff_explainer-0.1.0/README.md

@@ -1,47 +0,0 @@
-# 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.
-
-## 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
-```
-
-JSON output is intended for CI and integrations; text output is optimized for
-human review. The process exits with status 2 for unreadable files or expected
-SQL errors.

sql_diff_explainer-0.1.0/tests/test_core.py

@@ -1,64 +0,0 @@
-import pytest
-
-from sql_diff_explainer import SQLParseError, UnsupportedSQL, explain_diff, explain_sql_change
-
-
-def test_explain_diff_returns_unified_diff() -> None:
-    result = explain_diff("CREATE TABLE users;", "CREATE TABLE accounts;")
-
-    assert "--- before.sql" in result
-    assert "+++ after.sql" in result
-    assert "-CREATE TABLE users;" in result
-    assert "+CREATE TABLE accounts;" in result
-
-
-def test_explain_sql_change_detects_core_query_features() -> None:
-    before = (
-        "SELECT DISTINCT a, COUNT(*) FROM users u WHERE active = 1 "
-        "GROUP BY a ORDER BY a LIMIT 10"
-    )
-    after = (
-        "SELECT a, SUM(amount) FROM users u JOIN orders o ON u.id = o.user_id "
-        "WHERE active = 1 AND region = 'EU' GROUP BY a ORDER BY a DESC LIMIT 20 OFFSET 5"
-    )
-
-    result = explain_sql_change(before, after)
-    categories = {change.category for change in result.changes}
-
-    assert {"select", "join", "aggregation", "distinct", "limit", "offset"}.issubset(categories)
-    assert result.risk == "high"
-    assert result.to_dict()["changes"]
-
-
-def test_explain_sql_change_reports_filter_removal_as_high_risk() -> None:
-    result = explain_sql_change(
-        "SELECT id FROM users WHERE active = TRUE",
-        "SELECT id FROM users",
-    )
-
-    assert result.risk == "high"
-    assert any(change.category == "where" and change.risk == "high" for change in result.changes)
-
-
-def test_explain_sql_change_accepts_dialect() -> None:
-    result = explain_sql_change(
-        "SELECT TOP 5 id FROM users",
-        "SELECT TOP 10 id FROM users",
-        dialect="tsql",
-    )
-
-    assert result.changes[0].category == "limit"
-
-
-def test_parse_and_unsupported_errors_are_clean() -> None:
-    with pytest.raises(SQLParseError):
-        explain_sql_change("SELECT FROM", "SELECT 1")
-    with pytest.raises(UnsupportedSQL):
-        explain_sql_change("CREATE TABLE users (id INT)", "SELECT 1")
-
-
-def test_identical_queries_have_no_changes() -> None:
-    result = explain_sql_change("SELECT id FROM users", "SELECT id FROM users")
-
-    assert result.changes == []
-    assert result.risk == "low"