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

sql_diff_explainer/reports.py

@@ -84,6 +84,117 @@ def to_sarif(
                     },
                 )
             )
+        contract = sql_result.schema_contract
+        if contract and contract.get("supported"):
+            risks = {
+                "added": "medium",
+                "removed": "high",
+                "renamed": "medium",
+                "reordered": "medium",
+                "changed": "medium",
+                "type_changed": "high",
+            }
+            for item in contract.get("changes", []):
+                kind = item["kind"]
+                before = item["before"]
+                after = item["after"]
+                before_label = (
+                    f"{before['name']} ({before['type'] or 'type unknown'})"
+                    if before
+                    else "absent"
+                )
+                after_label = (
+                    f"{after['name']} ({after['type'] or 'type unknown'})"
+                    if after
+                    else "absent"
+                )
+                rule_id = f"sql-schema-{kind.replace('_', '-')}"
+                add_rule(
+                    rule_id,
+                    f"Output column {kind.replace('_', ' ')}",
+                    f"SQL output column {kind.replace('_', ' ')}",
+                )
+                sarif_results.append(
+                    _sarif_result(
+                        rule_id=rule_id,
+                        risk=risks[kind],
+                        message=(
+                            f"Output column {kind.replace('_', ' ')}: "
+                            f"{before_label} -> {after_label}."
+                        ),
+                        path=file_path,
+                        properties={"schema_change": item},
+                    )
+                )
+        elif contract:
+            rule_id = "sql-output-schema-unsupported"
+            add_rule(
+                rule_id,
+                "Output schema analysis unsupported",
+                "The output-schema contract could not be determined statically",
+            )
+            sarif_results.append(
+                _sarif_result(
+                    rule_id=rule_id,
+                    risk="low",
+                    message=(
+                        "Output-schema contract unsupported: "
+                        f"{contract.get('unsupported_reason')}"
+                    ),
+                    path=file_path,
+                    properties={
+                        "analysis": "output_schema",
+                        "supported": False,
+                        "reason": contract.get("unsupported_reason"),
+                    },
+                )
+            )
+        lineage = sql_result.lineage
+        if lineage and lineage.get("supported"):
+            for item in lineage.get("changes", []):
+                output = item["after"] or item["before"]
+                before = item["before"]
+                after = item["after"]
+                before_expression = before["expression"] if before else "absent"
+                after_expression = after["expression"] if after else "absent"
+                rule_id = "sql-cte-lineage-change"
+                add_rule(
+                    rule_id,
+                    "CTE lineage changed",
+                    "Source columns or expressions contributing to an output changed",
+                )
+                sarif_results.append(
+                    _sarif_result(
+                        rule_id=rule_id,
+                        risk="medium",
+                        message=(
+                            f"CTE lineage {item['kind']} for output {output['name']}: "
+                            f"{before_expression} -> {after_expression}."
+                        ),
+                        path=file_path,
+                        properties={"lineage_change": item},
+                    )
+                )
+        elif lineage:
+            rule_id = "sql-cte-lineage-unsupported"
+            add_rule(
+                rule_id,
+                "CTE lineage analysis unsupported",
+                "Source-to-output lineage could not be determined statically",
+            )
+            sarif_results.append(
+                _sarif_result(
+                    rule_id=rule_id,
+                    risk="low",
+                    message=f"CTE lineage unsupported: {lineage.get('unsupported_reason')}",
+                    path=file_path,
+                    properties={
+                        "analysis": "cte_lineage",
+                        "supported": False,
+                        "reason": lineage.get("unsupported_reason"),
+                    },
+                )
+            )
 
     if isinstance(result, SQLDiffResult):
         add_changes(result, path)
@@ -106,6 +217,18 @@ def to_sarif(
                         properties={"change": action},
                     )
                 )
+        if result.renamed_files:
+            add_rule("sql-file-renamed", "SQL file renamed", "SQL file renamed in the worktree")
+        for before_path, after_path in result.renamed_files:
+            sarif_results.append(
+                _sarif_result(
+                    rule_id="sql-file-renamed",
+                    risk="low",
+                    message=f"SQL file renamed: {before_path} -> {after_path}",
+                    path=after_path,
+                    properties={"change": "renamed", "before": before_path, "after": after_path},
+                )
+            )
 
     return {
         "$schema": _SARIF_SCHEMA,
@@ -131,6 +254,7 @@ def render_html_report(
 ) -> str:
     """Render a self-contained HTML report, escaping all SQL and path content."""
     rows: list[str] = []
+    details: list[str] = []
 
     def add_changes(sql_result: SQLDiffResult, file_path: str) -> None:
         for change in sql_result.changes:
@@ -143,6 +267,80 @@ def render_html_report(
                 f"<td><pre>{escape(change.after or '', quote=True)}</pre></td>"
                 "</tr>"
             )
+        prefix = f"{escape(file_path, quote=True)}: " if file_path else ""
+        contract = sql_result.schema_contract
+        if contract:
+            if contract.get("supported") is False:
+                details.append(
+                    "<li>"
+                    f"{prefix}output-schema contract unsupported: "
+                    f"{escape(str(contract.get('unsupported_reason')), quote=True)}"
+                    "</li>"
+                )
+            for item in contract.get("changes", []):
+                old = item["before"]
+                new = item["after"]
+                old_label = (
+                    f"{old['name']} ({old['type'] or 'type unknown'})" if old else "absent"
+                )
+                new_label = (
+                    f"{new['name']} ({new['type'] or 'type unknown'})" if new else "absent"
+                )
+                details.append(
+                    "<li>"
+                    f"{prefix}output column "
+                    f"{escape(item['kind'].replace('_', ' '), quote=True)}: "
+                    f"{escape(old_label, quote=True)} &rarr; "
+                    f"{escape(new_label, quote=True)}"
+                    "</li>"
+                )
+        lineage = sql_result.lineage
+        if lineage:
+            if lineage.get("supported") is False:
+                details.append(
+                    "<li>"
+                    f"{prefix}CTE lineage unsupported: "
+                    f"{escape(str(lineage.get('unsupported_reason')), quote=True)}"
+                    "</li>"
+                )
+            for item in lineage.get("changes", []):
+                old = item.get("before")
+                new = item.get("after")
+                name = (new or old)["name"]
+                old_sources = ", ".join(old["sources"]) if old else "none"
+                new_sources = ", ".join(new["sources"]) if new else "none"
+                old_expression = old["expression"] if old else "absent"
+                new_expression = new["expression"] if new else "absent"
+                details.append(
+                    "<li>"
+                    f"{prefix}CTE lineage {escape(item['kind'], quote=True)} for "
+                    f"{escape(name, quote=True)}: "
+                    f"{escape(old_expression, quote=True)} [{escape(old_sources, quote=True)}] "
+                    f"&rarr; {escape(new_expression, quote=True)} "
+                    f"[{escape(new_sources, quote=True)}]"
+                    "</li>"
+                )
+        for check in sql_result.validation_checks:
+            details.append(
+                "<li>"
+                f"{prefix}validation ({escape(check['kind'], quote=True)}): "
+                f"{escape(check['description'], quote=True)}"
+                + "".join(
+                    f"<ul><li>{escape(item, quote=True)}</li></ul>"
+                    for item in check["checklist"]
+                )
+                + "</li>"
+            )
+            if check["sql"]:
+                details.append(
+                    "<li><strong>Suggested SQL (not executed)</strong>"
+                    f"<pre>{escape(check['sql'], quote=True)}</pre></li>"
+                )
+            if check["unsupported_reason"]:
+                details.append(
+                    "<li>SQL not generated: "
+                    f"{escape(check['unsupported_reason'], quote=True)}</li>"
+                )
 
     if isinstance(result, SQLDiffResult):
         risk = result.risk
@@ -169,9 +367,23 @@ def render_html_report(
                 "<td>SQL file added.</td><td><pre></pre></td>"
                 "<td><pre>Present after</pre></td></tr>"
             )
+        for before_path, after_path in result.renamed_files:
+            rows.append(
+                "<tr>"
+                f"<td>{escape(after_path, quote=True)}</td>"
+                '<td class="low">LOW</td>'
+                f"<td>SQL file renamed from {escape(before_path, quote=True)}.</td>"
+                "<td><pre>Present before</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>')
+    details_section = (
+        ["<section><h2>Analysis details</h2><ul>", *details, "</ul></section>"]
+        if details
+        else []
+    )
     return "\n".join(
         [
             "<!doctype html>",
@@ -192,7 +404,9 @@ def render_html_report(
             "<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>",
+            "</tbody></table>",
+            *details_section,
+            "</body></html>",
             "",
         ]
     )

{sql_diff_explainer-0.1.3.dist-info → sql_diff_explainer-0.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sql-diff-explainer
-Version: 0.1.3
+Version: 0.1.5
 Summary: Explain SQL schema and migration differences
 Author: zmodz1010
 License: MIT
@@ -20,7 +20,7 @@ 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/)
+[![PyPI version](https://img.shields.io/pypi/v/sql-diff-explainer?cacheSeconds=60)](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)
 
@@ -29,7 +29,9 @@ than formatting.
 - [Quick start](#quick-start)
 - [Command-line usage](#command-line-usage)
 - [Directory comparison](#directory-comparison)
+- [Git-aware pull-request comparison](#git-aware-pull-request-comparison)
 - [SARIF and HTML reports](#sarif-and-html-reports)
+- [Additional SQL QA analyses](#additional-sql-qa-analyses)
 - [What it compares](#what-it-compares)
 - [Use cases](#use-cases)
 - [Scope and limitations](#scope-and-limitations)
@@ -113,8 +115,15 @@ Try the runnable before/after pairs in [`examples/`](examples/):
 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
+sql-diff-explainer examples/cte_lineage_before.sql examples/cte_lineage_after.sql --format json
+sql-diff-explainer examples/output_contract_before.sql examples/output_contract_after.sql --format json
+sql-diff-explainer --analyze-migration examples/migration.sql --format json
 ```
 
+`--analyze-migration FILE` accepts multi-statement migration scripts and emits
+text or JSON. It supports common `ALTER TABLE` column operations; SARIF and
+HTML formats are not available for this separate migration mode.
+
 ### Directory comparison
 
 Compare two directory trees recursively. SQL files are paired by their exact
@@ -141,6 +150,59 @@ result = compare_sql_directories("models/main", "models/review")
 print(result.to_dict())
 ```
 
+### Git-aware pull-request comparison
+
+Compare SQL paths Git reports as changed between a base ref and the current
+worktree. Modified files and SQL-to-SQL renames are compared semantically;
+added or removed SQL files are reported explicitly as high risk. Untracked
+files are not included. The base can be a branch, tag, or commit:
+
+```console
+sql-diff-explainer --git-base origin/main --format json
+sql-diff-explainer --git-base "$GITHUB_BASE_REF" --format sarif --output sql-diff.sarif
+sql-diff-explainer --git-base origin/main --fail-on-risk high
+```
+
+For GitHub Actions, fetch the base history and use the pull request's base
+commit. This example checks out the pull-request worktree, installs this
+repository's source (so the CLI includes the feature), emits SARIF, and fails
+the job on high-risk changes:
+
+```yaml
+name: SQL review
+on:
+  pull_request:
+
+jobs:
+  sql-diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install .
+      - name: Analyze changed SQL
+        run: >-
+          sql-diff-explainer
+          --git-base "${{ github.event.pull_request.base.sha }}"
+          --format sarif
+          --output sql-diff.sarif
+          --fail-on-risk high
+      - name: Upload SQL findings
+        if: always() && hashFiles('sql-diff.sarif') != ''
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: sql-diff.sarif
+```
+
+An unresolved base ref, Git failure, unreadable SQL, or invalid SQL exits with
+status `2` and a diagnostic. Renames appear in every report; a rename does not
+raise risk by itself, while semantic changes in its content retain their
+normal risk level.
+
 ### SARIF and HTML reports
 
 Emit SARIF 2.1.0 results for GitHub code scanning integrations, or generate a
@@ -158,6 +220,63 @@ and file paths. Python callers can use `to_sarif(result)` or
 `render_html_report(result)` with either `SQLDiffResult` or
 `SQLDirectoryDiffResult`.
 
+## Additional SQL QA analyses
+
+Query comparisons include three static QA views in `SQLDiffResult` and JSON
+output:
+
+- **CTE lineage** (`lineage`) traces explicit output expressions through
+  non-recursive CTE chains to their source columns. Changed sources or
+  expressions are also included in `changes` and the risk summary. Lineage
+  requires explicit projections, aliases for calculated expressions, and
+  direct table/CTE sources; recursive CTEs, wildcard projections, nested
+  subqueries, CTE column alias lists, and ambiguous unqualified columns are
+  reported as unsupported.
+- **Output-schema contracts** (`schema_contract`) report added, removed,
+  renamed, reordered, changed, and supported type-changed output columns.
+  Types are inferred only for explicit casts and aliased literals; column types
+  that require a database catalog remain unknown. Wildcard projections, unnamed
+  expressions, and set operations are reported as unsupported.
+- **Validation suggestions** (`validation_checks`) provide a checklist and,
+  when the before/after output columns are compatible, SQL for unmatched-row
+  and duplicate checks. The unmatched-row query uses `EXCEPT`; adapt it for
+  dialects that use different set-difference syntax. These checks are
+  suggestions only: SQL Diff Explainer never connects to a database or
+  executes generated SQL.
+
+Use the analysis helpers directly when needed:
+
+```python
+from sql_diff_explainer import (
+    analyze_migration,
+    compare_output_schema,
+    trace_cte_lineage,
+)
+
+before_sql = """
+WITH totals AS (SELECT customer_id, amount FROM sales)
+SELECT customer_id, amount FROM totals
+"""
+after_sql = """
+WITH totals AS (SELECT customer_id, net_amount AS amount FROM sales)
+SELECT customer_id, amount FROM totals
+"""
+
+lineage = trace_cte_lineage(before_sql, after_sql)
+contract = compare_output_schema(before_sql, after_sql)
+migration = analyze_migration(
+    "ALTER TABLE users ADD COLUMN email TEXT;"
+    "ALTER TABLE users RENAME COLUMN old_email TO email_address;"
+)
+print(lineage.to_dict(), contract.to_dict(), migration.to_dict())
+```
+
+Migration analysis recognizes `ADD COLUMN`, `DROP COLUMN`, `RENAME COLUMN`,
+`ALTER COLUMN ... TYPE`, and `ALTER COLUMN ... SET/DROP NOT NULL`. Other
+statements and ALTER actions are listed as unsupported rather than being
+silently treated as analyzed. Use `--analyze-migration` for a file or
+`analyze_migration(sql)` from Python.
+
 ## What it compares
 
 The analyzer compares supported `SELECT` query features and reports additions,
@@ -171,6 +290,7 @@ removals, or changes with a low, medium, or high risk classification:
 | Aggregation | Aggregate functions and `GROUP BY` expressions |
 | Ordering and pagination | `ORDER BY`, `LIMIT`, and `OFFSET` |
 | Duplicate handling | `DISTINCT` added or removed |
+| Output schema | Result-column additions, removals, renames, ordering, and known type changes |
 
 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
@@ -190,11 +310,14 @@ can affect which rows downstream consumers receive.
 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.
+business metric is correct. Output-column types that require database metadata
+are unknown. CTE lineage and query validation SQL support only the documented
+static cases, and migration analysis recognizes only the listed `ALTER TABLE`
+operations. Generated validation SQL is not executed and may need dialect
+adaptation. The analyzer does not 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
 

sql_diff_explainer-0.1.5.dist-info/RECORD

@@ -0,0 +1,10 @@
+sql_diff_explainer/__init__.py,sha256=aAC9OzousRZ9LohX-3rihFzxbsJIAEL-3u1mYw1mtPk,1479
+sql_diff_explainer/analysis.py,sha256=lpslLkUcszmlyK64-TWwhmuq1ywLpdM13nGdMglIfCU,29734
+sql_diff_explainer/cli.py,sha256=M95AFxK1yb_0DQNb1HLLmczq6DrWKKnS1rHuA6n1xRc,11292
+sql_diff_explainer/core.py,sha256=ZUtSCyocITV6FshwFjUjqu2oVTi6OJq5NsiT6IpSmAs,26854
+sql_diff_explainer/reports.py,sha256=Nz8cttmNJ0B0awIZDaCX5L2qFD4wcEZH36IsHv8_OJI,16573
+sql_diff_explainer-0.1.5.dist-info/METADATA,sha256=ype-3pwxVnNha6LbRuFJpcfKv5dwdgUjKhPaSlJ7zUU,12967
+sql_diff_explainer-0.1.5.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+sql_diff_explainer-0.1.5.dist-info/entry_points.txt,sha256=Pu2gG46es25JExzGO58plyLEsFedeCUM-TQnUeLpOlI,67
+sql_diff_explainer-0.1.5.dist-info/licenses/LICENSE,sha256=OJ2eEuGmpMxVb7jSmuVgeDcVHCEOMBkZgLgTlnK5mQQ,1087
+sql_diff_explainer-0.1.5.dist-info/RECORD,,

sql_diff_explainer-0.1.3.dist-info/RECORD

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