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

{sql_diff_explainer-0.1.4.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.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.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.4.dist-info/RECORD

@@ -1,9 +0,0 @@
-sql_diff_explainer/__init__.py,sha256=WLNMW_RRKVgtdpjVARZXURnFawVxN5eZn7z-s15tBP4,789
-sql_diff_explainer/cli.py,sha256=aOXVY-aivbe62DfERqxyGUNQ9QqadH6Bak3t3tPNn7s,5616
-sql_diff_explainer/core.py,sha256=cS-k8mgX_TWKQe1aX2HIZii5ial8DN2XLDU2-wkQjw4,23136
-sql_diff_explainer/reports.py,sha256=HrCFzxaxew-J62FQK4TC4mB-cTfEn6dLS8gLlvY24L0,8254
-sql_diff_explainer-0.1.4.dist-info/METADATA,sha256=mDI0Vyz1drIxfacjybYpUTHolar00roj1AN1GRE3_d0,9676
-sql_diff_explainer-0.1.4.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-sql_diff_explainer-0.1.4.dist-info/entry_points.txt,sha256=Pu2gG46es25JExzGO58plyLEsFedeCUM-TQnUeLpOlI,67
-sql_diff_explainer-0.1.4.dist-info/licenses/LICENSE,sha256=OJ2eEuGmpMxVb7jSmuVgeDcVHCEOMBkZgLgTlnK5mQQ,1087
-sql_diff_explainer-0.1.4.dist-info/RECORD,,