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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sql-diff-explainer
-Version: 0.1.4
+Version: 0.1.5
 Summary: Explain SQL schema and migration differences
 Author: zmodz1010
 License: MIT
@@ -31,6 +31,7 @@ than formatting.
 - [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)
@@ -114,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
@@ -212,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,
@@ -225,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
@@ -244,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.4 → sql_diff_explainer-0.1.5}/README.md

@@ -17,6 +17,7 @@ than formatting.
 - [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)
@@ -100,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
@@ -198,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,
@@ -211,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
@@ -230,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.4 → sql_diff_explainer-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sql-diff-explainer"
-version = "0.1.4"
+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"