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

sql_diff_explainer/cli.py

@@ -5,6 +5,7 @@ import json
 import sys
 from pathlib import Path
 
+from .analysis import MigrationAnalysisResult, analyze_migration
 from .core import (
     SQLDiffError,
     SQLDiffResult,
@@ -37,6 +38,12 @@ def main() -> int:
         metavar="REF",
         help="Compare Git-reported .sql changes from REF to the current worktree",
     )
+    parser.add_argument(
+        "--analyze-migration",
+        type=Path,
+        metavar="FILE",
+        help="Analyze common ALTER TABLE operations in a migration script",
+    )
     parser.add_argument("--dialect", help="sqlglot dialect used to parse both files")
     parser.add_argument(
         "--format",
@@ -54,22 +61,37 @@ def main() -> int:
 
     directory_mode = args.compare_dirs is not None
     git_mode = args.git_base is not None
-    selected_modes = sum((directory_mode, git_mode))
+    migration_mode = args.analyze_migration is not None
+    selected_modes = sum((directory_mode, git_mode, migration_mode))
     if selected_modes and (args.before is not None or args.after is not None):
-        parser.error("Use only one of --git-base, --compare-dirs, or the two SQL file arguments")
+        parser.error(
+            "Use only one of --git-base, --compare-dirs, --analyze-migration, "
+            "or the two SQL file arguments"
+        )
     if selected_modes > 1:
-        parser.error("Use either --git-base or --compare-dirs, not both")
+        parser.error("Choose only one of --git-base, --compare-dirs, or --analyze-migration")
     if not selected_modes and (args.before is None or args.after is None):
         parser.error(
-            "Provide two SQL files, use --compare-dirs BEFORE_DIR AFTER_DIR, or use --git-base REF"
+            "Provide two SQL files, use --compare-dirs BEFORE_DIR AFTER_DIR, "
+            "--git-base REF, or --analyze-migration FILE"
         )
+    if migration_mode and args.output_format in {"sarif", "html"}:
+        parser.error("--analyze-migration supports text and JSON output")
 
     try:
-        if git_mode:
+        if migration_mode:
+            result: SQLDiffResult | SQLDirectoryDiffResult | MigrationAnalysisResult = (
+                analyze_migration(
+                    args.analyze_migration.read_text(encoding="utf-8"),
+                    dialect=args.dialect,
+                )
+            )
+            report_path = ""
+        elif git_mode:
             result = compare_sql_git(args.git_base, dialect=args.dialect)
             report_path = ""
         elif directory_mode:
-            result: SQLDiffResult | SQLDirectoryDiffResult = compare_sql_directories(
+            result = compare_sql_directories(
                 args.compare_dirs[0],
                 args.compare_dirs[1],
                 dialect=args.dialect,
@@ -89,32 +111,118 @@ def main() -> int:
     if args.output_format == "json":
         report = json.dumps(result.to_dict(), indent=2)
     elif args.output_format == "sarif":
+        if isinstance(result, MigrationAnalysisResult):
+            raise AssertionError("Migration SARIF output should be rejected before analysis")
         report = json.dumps(to_sarif(result, path=report_path or "after.sql"), indent=2)
     elif args.output_format == "html":
+        if isinstance(result, MigrationAnalysisResult):
+            raise AssertionError("Migration HTML output should be rejected before analysis")
         report = render_html_report(result, path=report_path or "after.sql")
     else:
-        lines = [result.summary]
-        if isinstance(result, SQLDiffResult):
-            if result.risk_reasons:
-                lines.append(f"Risk: {result.risk.upper()} - {' '.join(result.risk_reasons)}")
-            file_results = [("", result)]
-        else:
-            file_results = [(item.path, item.result) for item in result.files]
-            lines.extend(f"Removed SQL file: {path}" for path in result.unmatched_before)
-            lines.extend(f"Added SQL file: {path}" for path in result.unmatched_after)
+        if isinstance(result, MigrationAnalysisResult):
+            lines = [result.summary]
+            for operation in result.operations:
+                lines.append(
+                    f"- [{operation.risk.upper()}] {operation.kind}: "
+                    f"{operation.table}.{operation.column}"
+                )
+                if operation.before is not None:
+                    lines.append(f"  before: {operation.before}")
+                if operation.after is not None:
+                    lines.append(f"  after:  {operation.after}")
             lines.extend(
-                f"Renamed SQL file: {before} -> {after}"
-                for before, after in result.renamed_files
+                f"- [UNSUPPORTED] {item.reason}: {item.statement}"
+                for item in result.unsupported
             )
-        for file_path, file_result in file_results:
-            if file_path and file_result.changes:
-                lines.append(f"{file_path}:")
-            for change in file_result.changes:
-                lines.append(f"- [{change.risk.upper()}] {change.description}")
-                if change.before is not None:
-                    lines.append(f"  before: {change.before}")
-                if change.after is not None:
-                    lines.append(f"  after:  {change.after}")
+        else:
+            lines = [result.summary]
+            if isinstance(result, SQLDiffResult):
+                if result.risk_reasons:
+                    lines.append(f"Risk: {result.risk.upper()} - {' '.join(result.risk_reasons)}")
+                file_results = [("", result)]
+            else:
+                file_results = [(item.path, item.result) for item in result.files]
+                lines.extend(f"Removed SQL file: {path}" for path in result.unmatched_before)
+                lines.extend(f"Added SQL file: {path}" for path in result.unmatched_after)
+                lines.extend(
+                    f"Renamed SQL file: {before} -> {after}"
+                    for before, after in result.renamed_files
+                )
+            for file_path, file_result in file_results:
+                if file_path and (
+                    file_result.changes
+                    or file_result.validation_checks
+                    or (
+                        file_result.lineage
+                        and (
+                            file_result.lineage.get("changes")
+                            or file_result.lineage.get("supported") is False
+                        )
+                    )
+                    or (
+                        file_result.schema_contract
+                        and (
+                            file_result.schema_contract.get("changes")
+                            or file_result.schema_contract.get("supported") is False
+                        )
+                    )
+                ):
+                    lines.append(f"{file_path}:")
+                for change in file_result.changes:
+                    lines.append(f"- [{change.risk.upper()}] {change.description}")
+                    if change.before is not None:
+                        lines.append(f"  before: {change.before}")
+                    if change.after is not None:
+                        lines.append(f"  after:  {change.after}")
+                if file_result.schema_contract is not None:
+                    contract = file_result.schema_contract
+                    if contract.get("supported") is False:
+                        lines.append(
+                            "  Output-schema contract unsupported: "
+                            f"{contract.get('unsupported_reason')}"
+                        )
+                    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"
+                        )
+                        lines.append(
+                            f"  Output schema {item['kind']}: {old_label} -> {new_label}"
+                        )
+                if file_result.lineage is not None:
+                    lineage = file_result.lineage
+                    if lineage.get("supported") is False:
+                        lines.append(
+                            f"  CTE lineage unsupported: {lineage.get('unsupported_reason')}"
+                        )
+                    for item in lineage.get("changes", []):
+                        old = item.get("before")
+                        new = item.get("after")
+                        old_sources = ", ".join(old["sources"]) if old else "none"
+                        new_sources = ", ".join(new["sources"]) if new else "none"
+                        output_name = (new or old)["name"]
+                        old_expression = old["expression"] if old else "absent"
+                        new_expression = new["expression"] if new else "absent"
+                        lines.append(
+                            f"  CTE lineage {item['kind']} for {output_name}: "
+                            f"{old_expression} [{old_sources}] -> "
+                            f"{new_expression} [{new_sources}]"
+                        )
+                for check in file_result.validation_checks:
+                    lines.append(
+                        f"  Validation suggestion (not executed, {check['kind']}): "
+                        f"{check['description']}"
+                    )
+                    if check["sql"]:
+                        lines.append(f"  SQL:\n{check['sql']}")
+                    for item in check["checklist"]:
+                        lines.append(f"  Checklist: {item}")
+                    if check["unsupported_reason"]:
+                        lines.append(f"  SQL not generated: {check['unsupported_reason']}")
         report = "\n".join(lines)
 
     try:
@@ -127,12 +235,15 @@ def main() -> int:
         print(f"error: Unable to write report: {exc}", file=sys.stderr)
         return 2
 
-    has_changes = (
-        bool(result.changes)
-        if isinstance(result, SQLDiffResult)
-        else any(item.result.changes for item in result.files)
-        or bool(result.unmatched_before or result.unmatched_after or result.renamed_files)
-    )
+    if isinstance(result, SQLDiffResult):
+        has_changes = bool(result.changes)
+    elif isinstance(result, SQLDirectoryDiffResult):
+        has_changes = (
+            any(item.result.changes for item in result.files)
+            or bool(result.unmatched_before or result.unmatched_after or result.renamed_files)
+        )
+    else:
+        has_changes = bool(result.operations or result.unsupported)
     if (
         args.fail_on_risk is not None
         and has_changes

sql_diff_explainer/core.py

@@ -83,6 +83,9 @@ class SQLDiffResult:
     risk: str = "low"
     risk_reasons: list[str] = field(default_factory=list)
     dialect: str | None = None
+    schema_contract: dict[str, object] | None = None
+    lineage: dict[str, object] | None = None
+    validation_checks: list[dict[str, object]] = field(default_factory=list)
 
     @property
     def risk_level(self) -> str:
@@ -103,6 +106,9 @@ class SQLDiffResult:
             "risk_reasons": list(self.risk_reasons),
             "dialect": self.dialect,
             "changes": [change.to_dict() for change in self.changes],
+            "schema_contract": self.schema_contract,
+            "lineage": self.lineage,
+            "validation_checks": list(self.validation_checks),
         }
 
 
@@ -413,7 +419,91 @@ def explain_sql_change(
         )[1]
         if reason and reason not in reasons:
             reasons.append(reason)
-    return SQLDiffResult(changes=changes, risk=overall, risk_reasons=reasons, dialect=dialect)
+    from .analysis import (
+        CTELineageDiff,
+        SchemaContractDiff,
+        compare_output_schema,
+        generate_validation_suggestions,
+        trace_cte_lineage,
+    )
+
+    schema_contract: SchemaContractDiff
+    lineage: CTELineageDiff | None = None
+    if isinstance(parser, SqlglotParser):
+        schema_contract = compare_output_schema(before, after, dialect=dialect)
+        if before_tree.args.get("with_") is not None or after_tree.args.get("with_") is not None:
+            lineage = trace_cte_lineage(before, after, dialect=dialect)
+    else:
+        schema_contract = SchemaContractDiff(
+            supported=False,
+            unsupported_reason="Output-schema analysis requires the SQLGlot parser.",
+        )
+    if schema_contract.supported:
+        for item in schema_contract.changes:
+            if item.kind != "reordered" or item.before is None or item.after is None:
+                continue
+            before_column = item.before
+            after_column = item.after
+            changes.append(
+                SQLChange(
+                    category="schema_contract",
+                    description=f"Output column {after_column.name} changed position.",
+                    before=f"{before_column.name} at position {before_column.position + 1}",
+                    after=f"{after_column.name} at position {after_column.position + 1}",
+                    risk="medium",
+                )
+            )
+            if severity["medium"] > severity[overall]:
+                overall = "medium"
+            reason = "Reordering output columns changes the result contract."
+            if reason not in reasons:
+                reasons.append(reason)
+    if lineage is not None and lineage.supported:
+        for item in lineage.changes:
+            before_lineage = item.before
+            after_lineage = item.after
+            before_text = (
+                f"{before_lineage.expression} <- {', '.join(before_lineage.sources)}"
+                if before_lineage
+                else None
+            )
+            after_text = (
+                f"{after_lineage.expression} <- {', '.join(after_lineage.sources)}"
+                if after_lineage
+                else None
+            )
+            risk = "high" if item.kind == "removed" else "medium"
+            changes.append(
+                SQLChange(
+                    category="cte_lineage",
+                    description=f"CTE lineage {item.kind} for output "
+                    f"{(after_lineage or before_lineage).name}.",
+                    before=before_text,
+                    after=after_text,
+                    risk=risk,
+                )
+            )
+            if severity[risk] > severity[overall]:
+                overall = risk
+            reason = "A CTE source or expression change can alter a final output."
+            if reason not in reasons:
+                reasons.append(reason)
+    validation_checks = generate_validation_suggestions(
+        before,
+        after,
+        changes,
+        schema_contract,
+        dialect=dialect,
+    )
+    return SQLDiffResult(
+        changes=changes,
+        risk=overall,
+        risk_reasons=reasons,
+        dialect=dialect,
+        schema_contract=schema_contract.to_dict(),
+        lineage=lineage.to_dict() if lineage else None,
+        validation_checks=[item.to_dict() for item in validation_checks],
+    )
 
 
 def compare_sql_directories(

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)
@@ -143,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:
@@ -155,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
@@ -193,6 +379,11 @@ def render_html_report(
 
     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>",
@@ -213,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>",
             "",
         ]
     )