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

sql_diff_explainer/cli.py

@@ -5,11 +5,13 @@ import json
 import sys
 from pathlib import Path
 
+from .analysis import MigrationAnalysisResult, analyze_migration
 from .core import (
     SQLDiffError,
     SQLDiffResult,
     SQLDirectoryDiffResult,
     compare_sql_directories,
+    compare_sql_git,
     explain_sql_change,
 )
 from .reports import render_html_report, to_sarif
@@ -31,6 +33,17 @@ def main() -> int:
         metavar=("BEFORE_DIR", "AFTER_DIR"),
         help="Recursively compare matching .sql files in two directories",
     )
+    parser.add_argument(
+        "--git-base",
+        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",
@@ -47,14 +60,38 @@ def main() -> int:
     args = parser.parse_args()
 
     directory_mode = args.compare_dirs is not None
-    if directory_mode and (args.before is not None or args.after is not None):
-        parser.error("Use either --compare-dirs or the two SQL file arguments, not both")
-    if not directory_mode and (args.before is None or args.after is None):
-        parser.error("Provide two SQL files or use --compare-dirs BEFORE_DIR AFTER_DIR")
+    git_mode = args.git_base is not None
+    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, --analyze-migration, "
+            "or the two SQL file arguments"
+        )
+    if selected_modes > 1:
+        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, "
+            "--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 directory_mode:
-            result: SQLDiffResult | SQLDirectoryDiffResult = compare_sql_directories(
+        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 = compare_sql_directories(
                 args.compare_dirs[0],
                 args.compare_dirs[1],
                 dialect=args.dialect,
@@ -74,28 +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)]
+        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"- [UNSUPPORTED] {item.reason}: {item.statement}"
+                for item in result.unsupported
+            )
         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)
-        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}")
+            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:
@@ -108,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)
-    )
+    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

@@ -2,11 +2,13 @@
 
 from __future__ import annotations
 
+import os
+import subprocess
 from abc import ABC, abstractmethod
 from collections import Counter
 from dataclasses import dataclass, field
 from difflib import unified_diff
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import Any
 
 
@@ -81,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:
@@ -101,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),
         }
 
 
@@ -122,6 +130,7 @@ class SQLDirectoryDiffResult:
     files: list[SQLFileDiff] = field(default_factory=list)
     unmatched_before: list[str] = field(default_factory=list)
     unmatched_after: list[str] = field(default_factory=list)
+    renamed_files: list[tuple[str, str]] = field(default_factory=list)
 
     @property
     def risk(self) -> str:
@@ -143,8 +152,13 @@ class SQLDirectoryDiffResult:
     def summary(self) -> str:
         changed = sum(bool(item.result.changes) for item in self.files)
         unmatched = len(self.unmatched_before) + len(self.unmatched_after)
-        if not changed and not unmatched:
+        if not changed and not unmatched and not self.renamed_files:
             return f"No structural SQL changes detected across {len(self.files)} file(s)."
+        if self.renamed_files:
+            return (
+                f"{changed} changed SQL file(s), {unmatched} unmatched SQL file(s), "
+                f"{len(self.renamed_files)} renamed SQL file(s); overall risk is {self.risk}."
+            )
         return (
             f"{changed} changed SQL file(s), {unmatched} unmatched SQL file(s); "
             f"overall risk is {self.risk}."
@@ -158,6 +172,9 @@ class SQLDirectoryDiffResult:
             "files": [item.to_dict() for item in self.files],
             "unmatched_before": list(self.unmatched_before),
             "unmatched_after": list(self.unmatched_after),
+            "renamed_files": [
+                {"before": before, "after": after} for before, after in self.renamed_files
+            ],
         }
 
 
@@ -402,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(
@@ -461,6 +562,137 @@ def compare_sql_directories(
     )
 
 
+def compare_sql_git(
+    base_ref: str,
+    *,
+    cwd: str | Path = ".",
+    dialect: str | None = None,
+    parser: SQLParser | None = None,
+) -> SQLDirectoryDiffResult:
+    """Compare Git-reported SQL changes from a base commit to the current worktree."""
+    working_dir = Path(cwd)
+
+    def run_git(*arguments: str) -> bytes:
+        try:
+            completed = subprocess.run(
+                ["git", *arguments],
+                cwd=working_dir,
+                capture_output=True,
+                check=False,
+            )
+        except OSError as exc:
+            raise SQLDiffError(f"Unable to run git: {exc}") from exc
+        if completed.returncode:
+            message = os.fsdecode(completed.stderr).strip()
+            raise SQLDiffError(f"Git command failed: {message or 'unknown git error'}")
+        return completed.stdout
+
+    root_output = run_git("rev-parse", "--show-toplevel").removesuffix(b"\n").removesuffix(b"\r")
+    root = Path(os.fsdecode(root_output))
+    commit = os.fsdecode(
+        run_git("rev-parse", "--verify", "--end-of-options", f"{base_ref}^{{commit}}")
+    ).strip()
+    if not commit:
+        raise SQLDiffError(f"Git base ref did not resolve to a commit: {base_ref}")
+
+    status_fields = run_git(
+        "diff", "--name-status", "-z", "--find-renames", commit, "--"
+    ).split(b"\0")
+    if status_fields and status_fields[-1] == b"":
+        status_fields.pop()
+
+    changed: list[tuple[str, str, str | None]] = []
+    index = 0
+    while index < len(status_fields):
+        status = os.fsdecode(status_fields[index])
+        index += 1
+        path_count = 2 if status.startswith(("R", "C")) else 1
+        if index + path_count > len(status_fields):
+            raise SQLDiffError("Git returned an incomplete file change record")
+        paths = [os.fsdecode(item) for item in status_fields[index : index + path_count]]
+        index += path_count
+        if path_count == 2:
+            changed.append((status[0], paths[0], paths[1]))
+        else:
+            changed.append(
+                (status[0], paths[0], None if status.startswith("D") else paths[0])
+            )
+
+    def validate_repo_path(path: str) -> None:
+        candidate = PurePosixPath(path)
+        if candidate.is_absolute() or "\\" in path or ".." in candidate.parts:
+            raise SQLDiffError(f"Unsafe path returned by git: {path!r}")
+
+    def read_base(path: str) -> str:
+        validate_repo_path(path)
+        try:
+            return run_git("cat-file", "blob", f"{commit}:{path}").decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise SQLDiffError(
+                f"Unable to read SQL file as UTF-8 from Git base ({path}): {exc}"
+            ) from exc
+        except SQLDiffError as exc:
+            raise SQLDiffError(f"Unable to read SQL file from Git base ({path}): {exc}") from exc
+
+    def read_worktree(path: str) -> str:
+        validate_repo_path(path)
+        file_path = root.joinpath(*PurePosixPath(path).parts)
+        try:
+            resolved = file_path.resolve(strict=True)
+            if not resolved.is_relative_to(root.resolve()):
+                raise SQLDiffError(f"SQL file path resolves outside the Git repository: {path}")
+            if not resolved.is_file():
+                raise SQLDiffError(f"SQL path is not a file in the worktree: {path}")
+            return resolved.read_text(encoding="utf-8")
+        except UnicodeDecodeError as exc:
+            raise SQLDiffError(f"Unable to read SQL file as UTF-8 ({path}): {exc}") from exc
+        except OSError as exc:
+            raise SQLDiffError(f"Unable to read SQL file from worktree ({path}): {exc}") from exc
+
+    def is_sql(path: str) -> bool:
+        return PurePosixPath(path).suffix.lower() == ".sql"
+
+    files: list[SQLFileDiff] = []
+    removed: list[str] = []
+    added: list[str] = []
+    renamed: list[tuple[str, str]] = []
+    for status, before_path, after_path in changed:
+        if after_path is None:
+            if is_sql(before_path):
+                removed.append(before_path)
+            continue
+
+        before_is_sql = is_sql(before_path)
+        after_is_sql = is_sql(after_path)
+        if status == "A":
+            if after_is_sql:
+                added.append(after_path)
+            continue
+        if before_is_sql and after_is_sql:
+            if before_path != after_path:
+                renamed.append((before_path, after_path))
+            files.append(
+                SQLFileDiff(
+                    after_path,
+                    explain_sql_change(
+                        read_base(before_path), read_worktree(after_path),
+                        dialect=dialect, parser=parser,
+                    ),
+                )
+            )
+        elif before_is_sql:
+            removed.append(before_path)
+        elif after_is_sql:
+            added.append(after_path)
+
+    return SQLDirectoryDiffResult(
+        files=sorted(files, key=lambda item: item.path),
+        unmatched_before=sorted(removed),
+        unmatched_after=sorted(added),
+        renamed_files=sorted(renamed),
+    )
+
+
 def explain_diff(before: str, after: str) -> str:
     """Return a readable unified diff for two SQL documents."""
     lines = unified_diff(