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

{sql_diff_explainer-0.1.3 → sql_diff_explainer-0.1.5}/PKG-INFO

@@ -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.3 → sql_diff_explainer-0.1.5}/README.md

@@ -6,7 +6,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)
 
@@ -15,7 +15,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)
@@ -99,8 +101,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
@@ -127,6 +136,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
@@ -144,6 +206,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,
@@ -157,6 +276,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
@@ -176,11 +296,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/examples/cte_lineage_after.sql

@@ -0,0 +1,7 @@
+WITH order_totals AS (
+    SELECT customer_id, SUM(net_amount) AS total_amount
+    FROM orders
+    GROUP BY customer_id
+)
+SELECT customer_id, total_amount
+FROM order_totals

sql_diff_explainer-0.1.5/examples/cte_lineage_before.sql

@@ -0,0 +1,7 @@
+WITH order_totals AS (
+    SELECT customer_id, SUM(amount) AS total_amount
+    FROM orders
+    GROUP BY customer_id
+)
+SELECT customer_id, total_amount
+FROM order_totals

sql_diff_explainer-0.1.5/examples/migration.sql

@@ -0,0 +1,4 @@
+ALTER TABLE customers ADD COLUMN email TEXT;
+ALTER TABLE customers RENAME COLUMN name TO display_name;
+ALTER TABLE customers ALTER COLUMN customer_id TYPE BIGINT;
+ALTER TABLE customers DROP COLUMN legacy_status;

sql_diff_explainer-0.1.5/examples/output_contract_after.sql

@@ -0,0 +1,4 @@
+SELECT
+    CAST(customer_id AS BIGINT) AS customer_id,
+    name AS display_name
+FROM customers

sql_diff_explainer-0.1.5/examples/output_contract_before.sql

@@ -0,0 +1,5 @@
+SELECT
+    CAST(customer_id AS INT) AS customer_id,
+    name AS customer_name,
+    legacy_status
+FROM customers

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

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

sql_diff_explainer-0.1.5/src/sql_diff_explainer/__init__.py

@@ -0,0 +1,65 @@
+"""Tools for explaining SQL query differences."""
+
+from .analysis import (
+    CTELineageDiff,
+    LineageChange,
+    MigrationAnalysisResult,
+    MigrationOperation,
+    OutputLineage,
+    SchemaChange,
+    SchemaColumn,
+    SchemaContractDiff,
+    UnsupportedMigrationStatement,
+    ValidationSuggestion,
+    analyze_migration,
+    compare_output_schema,
+    trace_cte_lineage,
+)
+from .core import (
+    SQLChange,
+    SQLDiffError,
+    SQLDiffResult,
+    SQLDirectoryDiffResult,
+    SQLFileDiff,
+    SqlglotParser,
+    SQLParseError,
+    SQLParser,
+    UnsupportedSQL,
+    compare_sql_directories,
+    compare_sql_git,
+    explain_diff,
+    explain_sql_change,
+)
+from .reports import render_html_report, to_sarif
+
+__all__ = [
+    "CTELineageDiff",
+    "LineageChange",
+    "MigrationAnalysisResult",
+    "MigrationOperation",
+    "OutputLineage",
+    "SchemaChange",
+    "SchemaColumn",
+    "SchemaContractDiff",
+    "SQLChange",
+    "SQLDirectoryDiffResult",
+    "SQLDiffError",
+    "SQLDiffResult",
+    "SQLFileDiff",
+    "SQLParseError",
+    "SQLParser",
+    "SqlglotParser",
+    "UnsupportedSQL",
+    "UnsupportedMigrationStatement",
+    "ValidationSuggestion",
+    "analyze_migration",
+    "compare_sql_directories",
+    "compare_sql_git",
+    "compare_output_schema",
+    "explain_diff",
+    "explain_sql_change",
+    "render_html_report",
+    "trace_cte_lineage",
+    "to_sarif",
+]
+__version__ = "0.1.5"