sql-diff-explainer 0.1.1__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.1 → sql_diff_explainer-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sql-diff-explainer"
-version = "0.1.1"
+version = "0.1.2"
 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.2}/src/sql_diff_explainer/__init__.py

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

{sql_diff_explainer-0.1.1 → 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.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.1/PKG-INFO

@@ -1,65 +0,0 @@
-Metadata-Version: 2.5
-Name: sql-diff-explainer
-Version: 0.1.1
-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 current patch release is **0.1.1**. It includes the stable `risk_level`
-compatibility property, semantic join-type pairing, and high-risk classification
-for outer-to-inner join changes.
-
-## 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.1/README.md

@@ -1,51 +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.
-
-The current patch release is **0.1.1**. It includes the stable `risk_level`
-compatibility property, semantic join-type pairing, and high-risk classification
-for outer-to-inner join changes.
-
-## 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.1/tests/test_core.py

@@ -1,79 +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.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")