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

sql_diff_explainer/__init__.py

@@ -4,23 +4,34 @@ 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__ = [
     "SQLChange",
+    "SQLDirectoryDiffResult",
     "SQLDiffError",
     "SQLDiffResult",
+    "SQLFileDiff",
     "SQLParseError",
     "SQLParser",
     "SqlglotParser",
     "UnsupportedSQL",
+    "compare_sql_directories",
+    "compare_sql_git",
     "explain_diff",
     "explain_sql_change",
+    "render_html_report",
+    "to_sarif",
 ]
-__version__ = "0.1.2"
+__version__ = "0.1.4"

sql_diff_explainer/cli.py

@@ -5,7 +5,15 @@ import json
 import sys
 from pathlib import Path
 
-from .core import SQLDiffError, explain_sql_change
+from .core import (
+    SQLDiffError,
+    SQLDiffResult,
+    SQLDirectoryDiffResult,
+    compare_sql_directories,
+    compare_sql_git,
+    explain_sql_change,
+)
+from .reports import render_html_report, to_sarif
 
 _RISK_SEVERITY = {"low": 0, "medium": 1, "high": 2}
 
@@ -13,12 +21,30 @@ _RISK_SEVERITY = {"low": 0, "medium": 1, "high": 2}
 def main() -> int:
     """Run the command-line interface."""
     parser = argparse.ArgumentParser(
-        description="Explain structural differences between two SQL files."
+        description="Explain structural differences between SQL files or directories."
+    )
+    parser.add_argument("before", type=Path, nargs="?", help="Original SQL file")
+    parser.add_argument("after", type=Path, nargs="?", help="Updated SQL file")
+    parser.add_argument(
+        "--compare-dirs",
+        nargs=2,
+        type=Path,
+        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("before", type=Path, help="Original SQL file")
-    parser.add_argument("after", type=Path, help="Updated SQL file")
     parser.add_argument("--dialect", help="sqlglot dialect used to parse both files")
-    parser.add_argument("--format", choices=("text", "json"), default="text", dest="output_format")
+    parser.add_argument(
+        "--format",
+        choices=("text", "json", "sarif", "html"),
+        default="text",
+        dest="output_format",
+    )
+    parser.add_argument("--output", type=Path, help="Write the report to this file")
     parser.add_argument(
         "--fail-on-risk",
         choices=tuple(_RISK_SEVERITY),
@@ -26,30 +52,90 @@ def main() -> int:
     )
     args = parser.parse_args()
 
-    try:
-        result = explain_sql_change(
-            args.before.read_text(encoding="utf-8"),
-            args.after.read_text(encoding="utf-8"),
-            dialect=args.dialect,
+    directory_mode = args.compare_dirs is not None
+    git_mode = args.git_base is not None
+    selected_modes = sum((directory_mode, git_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")
+    if selected_modes > 1:
+        parser.error("Use either --git-base or --compare-dirs, not both")
+    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"
         )
-    except (OSError, SQLDiffError) as exc:
+
+    try:
+        if git_mode:
+            result = compare_sql_git(args.git_base, dialect=args.dialect)
+            report_path = ""
+        elif directory_mode:
+            result: SQLDiffResult | SQLDirectoryDiffResult = compare_sql_directories(
+                args.compare_dirs[0],
+                args.compare_dirs[1],
+                dialect=args.dialect,
+            )
+            report_path = ""
+        else:
+            result = explain_sql_change(
+                args.before.read_text(encoding="utf-8"),
+                args.after.read_text(encoding="utf-8"),
+                dialect=args.dialect,
+            )
+            report_path = args.after.as_posix()
+    except (OSError, UnicodeDecodeError, SQLDiffError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
+
     if args.output_format == "json":
-        print(json.dumps(result.to_dict(), indent=2))
+        report = json.dumps(result.to_dict(), indent=2)
+    elif args.output_format == "sarif":
+        report = json.dumps(to_sarif(result, path=report_path or "after.sql"), indent=2)
+    elif args.output_format == "html":
+        report = render_html_report(result, path=report_path or "after.sql")
     else:
-        print(result.summary)
-        if result.risk_reasons:
-            print(f"Risk: {result.risk.upper()} - {' '.join(result.risk_reasons)}")
-        for change in result.changes:
-            print(f"- [{change.risk.upper()}] {change.description}")
-            if change.before is not None:
-                print(f"  before: {change.before}")
-            if change.after is not None:
-                print(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:
+                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}")
+        report = "\n".join(lines)
+
+    try:
+        if args.output is None:
+            print(report)
+        else:
+            output_text = report if report.endswith("\n") else report + "\n"
+            args.output.write_text(output_text, encoding="utf-8")
+    except OSError as exc:
+        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 (
         args.fail_on_risk is not None
-        and result.changes
+        and has_changes
         and _RISK_SEVERITY[result.risk] >= _RISK_SEVERITY[args.fail_on_risk]
     ):
         return 1

sql_diff_explainer/core.py

@@ -2,10 +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, PurePosixPath
 from typing import Any
 
 
@@ -103,6 +106,72 @@ class SQLDiffResult:
         }
 
 
+@dataclass(frozen=True)
+class SQLFileDiff:
+    """The semantic comparison for one matched relative SQL file path."""
+
+    path: str
+    result: SQLDiffResult
+
+    def to_dict(self) -> dict[str, object]:
+        return {"path": self.path, **self.result.to_dict()}
+
+
+@dataclass
+class SQLDirectoryDiffResult:
+    """Comparisons and unmatched SQL files from two directory trees."""
+
+    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:
+        """Return the highest file risk; whole-file additions/removals are high risk."""
+        if self.unmatched_before or self.unmatched_after:
+            return "high"
+        severity = {"low": 0, "medium": 1, "high": 2}
+        return max(
+            (item.result.risk for item in self.files),
+            key=severity.__getitem__,
+            default="low",
+        )
+
+    @property
+    def risk_level(self) -> str:
+        return self.risk
+
+    @property
+    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 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}."
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "summary": self.summary,
+            "risk": self.risk,
+            "risk_level": self.risk_level,
+            "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
+            ],
+        }
+
+
 def _sql(node: Any, dialect: str | None) -> str | None:
     if node is None:
         return None
@@ -347,6 +416,193 @@ def explain_sql_change(
     return SQLDiffResult(changes=changes, risk=overall, risk_reasons=reasons, dialect=dialect)
 
 
+def compare_sql_directories(
+    before_dir: str | Path,
+    after_dir: str | Path,
+    *,
+    dialect: str | None = None,
+    parser: SQLParser | None = None,
+) -> SQLDirectoryDiffResult:
+    """Compare recursively discovered SQL files paired by exact relative path.
+
+    Files present on only one side are returned as unmatched instead of being
+    parsed as empty SQL. An unmatched file makes the aggregate risk high.
+    """
+    before_root = Path(before_dir)
+    after_root = Path(after_dir)
+    for label, root in (("before", before_root), ("after", after_root)):
+        if not root.exists():
+            raise SQLDiffError(f"{label} directory does not exist: {root}")
+        if not root.is_dir():
+            raise SQLDiffError(f"{label} path is not a directory: {root}")
+
+    def discover(root: Path) -> dict[str, Path]:
+        return {
+            path.relative_to(root).as_posix(): path
+            for path in sorted(root.rglob("*"))
+            if path.is_file() and path.suffix.lower() == ".sql"
+        }
+
+    before_files = discover(before_root)
+    after_files = discover(after_root)
+    before_paths = set(before_files)
+    after_paths = set(after_files)
+    shared_paths = sorted(before_paths & after_paths)
+    try:
+        comparisons = [
+            SQLFileDiff(
+                path=relative_path,
+                result=explain_sql_change(
+                    before_files[relative_path].read_text(encoding="utf-8"),
+                    after_files[relative_path].read_text(encoding="utf-8"),
+                    dialect=dialect,
+                    parser=parser,
+                ),
+            )
+            for relative_path in shared_paths
+        ]
+    except UnicodeDecodeError as exc:
+        raise SQLDiffError(f"Unable to read SQL file as UTF-8: {exc}") from exc
+    except OSError as exc:
+        raise SQLDiffError(f"Unable to read SQL file: {exc}") from exc
+    return SQLDirectoryDiffResult(
+        files=comparisons,
+        unmatched_before=sorted(before_paths - after_paths),
+        unmatched_after=sorted(after_paths - before_paths),
+    )
+
+
+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(

sql_diff_explainer/reports.py

@@ -0,0 +1,219 @@
+"""Machine-readable and standalone HTML reports for SQL comparisons."""
+
+from __future__ import annotations
+
+from html import escape
+from pathlib import Path
+from urllib.parse import quote
+
+from .core import SQLDiffResult, SQLDirectoryDiffResult
+
+_SARIF_LEVEL = {"low": "note", "medium": "warning", "high": "error"}
+_SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+
+
+def _artifact_uri(path: str) -> str:
+    candidate = Path(path)
+    if candidate.is_absolute():
+        return candidate.as_uri()
+    return quote(candidate.as_posix(), safe="/-._~")
+
+
+def _sarif_result(
+    *,
+    rule_id: str,
+    risk: str,
+    message: str,
+    path: str,
+    properties: dict[str, object] | None = None,
+) -> dict[str, object]:
+    result: dict[str, object] = {
+        "ruleId": rule_id,
+        "level": _SARIF_LEVEL[risk],
+        "message": {"text": message},
+        "locations": [
+            {
+                "physicalLocation": {
+                    "artifactLocation": {"uri": _artifact_uri(path)},
+                }
+            }
+        ],
+        "properties": {"risk": risk, **(properties or {})},
+    }
+    return result
+
+
+def to_sarif(
+    result: SQLDiffResult | SQLDirectoryDiffResult,
+    *,
+    path: str = "after.sql",
+) -> dict[str, object]:
+    """Convert a single-file or directory comparison to a SARIF 2.1.0 document."""
+    sarif_results: list[dict[str, object]] = []
+    rules: dict[str, dict[str, object]] = {}
+
+    def add_rule(rule_id: str, name: str, description: str) -> None:
+        rules.setdefault(
+            rule_id,
+            {
+                "id": rule_id,
+                "name": name,
+                "shortDescription": {"text": description},
+            },
+        )
+
+    def add_changes(sql_result: SQLDiffResult, file_path: str) -> None:
+        for change in sql_result.changes:
+            rule_id = f"sql-diff-{change.category.replace('_', '-')}"
+            add_rule(rule_id, change.category, f"SQL {change.category.replace('_', ' ')} change")
+            message = change.description
+            if change.before is not None:
+                message += f" Before: {change.before}"
+            if change.after is not None:
+                message += f" After: {change.after}"
+            sarif_results.append(
+                _sarif_result(
+                    rule_id=rule_id,
+                    risk=change.risk,
+                    message=message,
+                    path=file_path,
+                    properties={
+                        "category": change.category,
+                        "before": change.before,
+                        "after": change.after,
+                    },
+                )
+            )
+
+    if isinstance(result, SQLDiffResult):
+        add_changes(result, path)
+    else:
+        for file_diff in result.files:
+            add_changes(file_diff.result, file_diff.path)
+        for unmatched, rule_id, action in (
+            (result.unmatched_before, "sql-file-removed", "removed"),
+            (result.unmatched_after, "sql-file-added", "added"),
+        ):
+            if unmatched:
+                add_rule(rule_id, f"SQL file {action}", f"SQL file {action} between directories")
+            for file_path in unmatched:
+                sarif_results.append(
+                    _sarif_result(
+                        rule_id=rule_id,
+                        risk="high",
+                        message=f"SQL file {action}: {file_path}",
+                        path=file_path,
+                        properties={"change": action},
+                    )
+                )
+        if result.renamed_files:
+            add_rule("sql-file-renamed", "SQL file renamed", "SQL file renamed in the worktree")
+        for before_path, after_path in result.renamed_files:
+            sarif_results.append(
+                _sarif_result(
+                    rule_id="sql-file-renamed",
+                    risk="low",
+                    message=f"SQL file renamed: {before_path} -> {after_path}",
+                    path=after_path,
+                    properties={"change": "renamed", "before": before_path, "after": after_path},
+                )
+            )
+
+    return {
+        "$schema": _SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "SQL Diff Explainer",
+                        "rules": list(rules.values()),
+                    }
+                },
+                "results": sarif_results,
+            }
+        ],
+    }
+
+
+def render_html_report(
+    result: SQLDiffResult | SQLDirectoryDiffResult,
+    *,
+    path: str = "after.sql",
+) -> str:
+    """Render a self-contained HTML report, escaping all SQL and path content."""
+    rows: list[str] = []
+
+    def add_changes(sql_result: SQLDiffResult, file_path: str) -> None:
+        for change in sql_result.changes:
+            rows.append(
+                "<tr>"
+                f"<td>{escape(file_path, quote=True)}</td>"
+                f'<td class="{escape(change.risk, quote=True)}">{escape(change.risk.upper())}</td>'
+                f"<td>{escape(change.description, quote=True)}</td>"
+                f"<td><pre>{escape(change.before or '', quote=True)}</pre></td>"
+                f"<td><pre>{escape(change.after or '', quote=True)}</pre></td>"
+                "</tr>"
+            )
+
+    if isinstance(result, SQLDiffResult):
+        risk = result.risk
+        summary = result.summary
+        add_changes(result, path)
+    else:
+        risk = result.risk
+        summary = result.summary
+        for file_diff in result.files:
+            add_changes(file_diff.result, file_diff.path)
+        for file_path in result.unmatched_before:
+            rows.append(
+                "<tr>"
+                f"<td>{escape(file_path, quote=True)}</td>"
+                '<td class="high">HIGH</td>'
+                "<td>SQL file removed.</td><td><pre>Present before</pre></td>"
+                "<td><pre></pre></td></tr>"
+            )
+        for file_path in result.unmatched_after:
+            rows.append(
+                "<tr>"
+                f"<td>{escape(file_path, quote=True)}</td>"
+                '<td class="high">HIGH</td>'
+                "<td>SQL file added.</td><td><pre></pre></td>"
+                "<td><pre>Present after</pre></td></tr>"
+            )
+        for before_path, after_path in result.renamed_files:
+            rows.append(
+                "<tr>"
+                f"<td>{escape(after_path, quote=True)}</td>"
+                '<td class="low">LOW</td>'
+                f"<td>SQL file renamed from {escape(before_path, quote=True)}.</td>"
+                "<td><pre>Present before</pre></td>"
+                "<td><pre>Present after</pre></td></tr>"
+            )
+
+    if not rows:
+        rows.append('<tr><td colspan="5">No structural SQL changes detected.</td></tr>')
+    return "\n".join(
+        [
+            "<!doctype html>",
+            '<html lang="en"><head><meta charset="utf-8">',
+            '<meta name="viewport" content="width=device-width, initial-scale=1">',
+            "<title>SQL Diff Explainer report</title>",
+            "<style>",
+            "body{font:15px system-ui,sans-serif;margin:2rem;color:#24292f}"
+            "table{border-collapse:collapse;width:100%}th,td{border:1px solid #d0d7de;"
+            "padding:.6rem;text-align:left;vertical-align:top}pre{white-space:pre-wrap;"
+            "overflow-wrap:anywhere;margin:0}.high{color:#cf222e}.medium{color:#9a6700}"
+            ".low{color:#1a7f37}",
+            "</style></head><body>",
+            "<h1>SQL Diff Explainer</h1>",
+            f'<p class="{escape(risk, quote=True)}">Overall risk: '
+            f"{escape(risk.upper(), quote=True)}</p>",
+            f"<p>{escape(summary, quote=True)}</p>",
+            "<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>",
+            "",
+        ]
+    )

sql_diff_explainer-0.1.4.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.5
+Name: sql-diff-explainer
+Version: 0.1.4
+Summary: Explain SQL schema and migration differences
+Author: zmodz1010
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: sqlglot>=25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SQL Diff Explainer
+
+**See what changed in a SQL query—and why it might matter.**
+
+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?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)
+
+## Contents
+
+- [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)
+- [What it compares](#what-it-compares)
+- [Use cases](#use-cases)
+- [Scope and limitations](#scope-and-limitations)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Quick start
+
+Install the latest release from [PyPI](https://pypi.org/project/sql-diff-explainer/):
+
+```console
+python -m pip install sql-diff-explainer
+```
+
+Compare two queries from Python:
+
+```python
+from sql_diff_explainer import explain_sql_change
+
+before = """
+SELECT c.customer_id, c.segment, o.order_id
+FROM customers AS c
+LEFT JOIN orders AS o ON c.customer_id = o.customer_id
+"""
+after = """
+SELECT c.customer_id, c.segment, o.order_id
+FROM customers AS c
+INNER JOIN orders AS o ON c.customer_id = o.customer_id
+"""
+
+result = explain_sql_change(before, after)
+print(result.summary)
+for change in result.changes:
+    print(
+        f"{change.category}: {change.before} -> {change.after} "
+        f"({change.risk} risk)"
+    )
+```
+
+Output:
+
+```text
+1 SQL change(s) detected; overall risk is high.
+join: LEFT JOIN orders AS o ON c.customer_id = o.customer_id -> INNER JOIN orders AS o ON c.customer_id = o.customer_id (high risk)
+```
+
+The change is classified as high risk because an `INNER JOIN` excludes
+customers without a matching order, whereas a `LEFT JOIN` retains them. The
+result is structured: inspect `result.risk_level` and `result.changes`, or call
+`result.to_dict()` for JSON-ready data. Pass `dialect="postgres"` (or another
+[sqlglot dialect](https://sqlglot.com/sqlglot/dialects.html)) for
+dialect-specific SQL. Invalid SQL raises `SQLParseError`; non-`SELECT` input
+raises `UnsupportedSQL`.
+
+## Command-line usage
+
+The CLI compares two SQL files and prints a human-readable report by default:
+
+```console
+sql-diff-explainer examples/join_before.sql examples/join_after.sql
+```
+
+Choose JSON output, set a parsing dialect, or make a risk threshold fail a CI
+step:
+
+```console
+sql-diff-explainer before.sql after.sql --format json
+sql-diff-explainer before.sql after.sql --dialect postgres
+sql-diff-explainer before.sql after.sql --fail-on-risk medium
+```
+
+`--fail-on-risk` accepts `low`, `medium`, or `high`. It exits with status `1`
+when detected changes meet or exceed the threshold; the text or JSON report is
+still printed. No detected changes exit successfully. Input-file errors and
+SQL parse/support errors exit with status `2`.
+
+Try the runnable before/after pairs in [`examples/`](examples/):
+
+```console
+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
+```
+
+### Directory comparison
+
+Compare two directory trees recursively. SQL files are paired by their exact
+relative path (with `/` separators); the `.sql` extension is matched
+case-insensitively. Files present on only one side are reported as additions
+or removals rather than parsed as empty SQL, and raise the aggregate risk to
+high:
+
+```console
+sql-diff-explainer --compare-dirs models/main models/review --format json
+sql-diff-explainer --compare-dirs models/main models/review --fail-on-risk high
+```
+
+The JSON report includes each matched file's ordinary SQL diff, plus
+`unmatched_before` and `unmatched_after` path lists. A missing or non-directory
+input, unreadable file, or invalid SQL exits with status `2`.
+
+The same operation is available in Python:
+
+```python
+from sql_diff_explainer import compare_sql_directories
+
+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
+self-contained HTML report that can be attached to a review:
+
+```console
+sql-diff-explainer before.sql after.sql --format sarif --output sql-diff.sarif
+sql-diff-explainer --compare-dirs models/main models/review --format html --output review.html
+```
+
+Both formats work with the existing `--fail-on-risk` threshold. SARIF maps
+high, medium, and low risk to `error`, `warning`, and `note`; report output is
+still written when the threshold causes exit status `1`. HTML escapes SQL text
+and file paths. Python callers can use `to_sarif(result)` or
+`render_html_report(result)` with either `SQLDiffResult` or
+`SQLDirectoryDiffResult`.
+
+## What it compares
+
+The analyzer compares supported `SELECT` query features and reports additions,
+removals, or changes with a low, medium, or high risk classification:
+
+| Feature | Examples of changes |
+| --- | --- |
+| Projections | Selected columns and expressions |
+| Joins | Join target, predicate, or type |
+| Filters | `WHERE` predicates |
+| Aggregation | Aggregate functions and `GROUP BY` expressions |
+| Ordering and pagination | `ORDER BY`, `LIMIT`, and `OFFSET` |
+| Duplicate handling | `DISTINCT` added or removed |
+
+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
+can affect which rows downstream consumers receive.
+
+## Use cases
+
+- Review dbt models or warehouse SQL in a pull request.
+- Spot join and filter changes that could alter row counts.
+- Check grouping and aggregation changes that could shift metric grain.
+- Add a lightweight risk threshold to a CI check.
+- Explain generated SQL changes without treating formatting-only differences
+  as query changes.
+
+## Scope and limitations
+
+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.
+
+## Development
+
+The package requires Python 3.10 or newer and uses a `src/` layout.
+
+```console
+python -m venv .venv
+```
+
+Activate the environment, then install the development dependencies and run
+the checks:
+
+```console
+# macOS / Linux
+source .venv/bin/activate
+
+# Windows PowerShell
+.venv\Scripts\Activate.ps1
+
+python -m pip install -e ".[dev]"
+python -m pytest
+ruff check .
+```
+
+## Contributing
+
+Bug reports, focused improvements, and pull requests are welcome. Please
+include or update tests for behavior changes and keep documentation aligned
+with the supported API.
+
+## License
+
+Distributed under the [MIT License](LICENSE).

sql_diff_explainer-0.1.4.dist-info/RECORD

@@ -0,0 +1,9 @@
+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,,

sql_diff_explainer-0.1.2.dist-info/METADATA

@@ -1,147 +0,0 @@
-Metadata-Version: 2.5
-Name: sql-diff-explainer
-Version: 0.1.2
-Summary: Explain SQL schema and migration differences
-Author: zmodz1010
-License: MIT
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: sqlglot>=25.0
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff>=0.6; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# SQL Diff Explainer
-
-Explain the meaningful structural differences between two SQL `SELECT` queries.
-
-The package uses [sqlglot](https://github.com/tobymao/sqlglot) behind an abstract
-parser interface, so callers receive a stable result even if the parser
-implementation changes. It reports changes to projections, joins, filters,
-grouping, aggregation, ordering, pagination, and `DISTINCT`, with a static
-low/medium/high risk classification.
-
-The next patch release is **0.1.2**. It adds the CI-friendly CLI
-`--fail-on-risk` threshold.
-
-## Why use SQL Diff Explainer?
-
-Use it in a pull request, migration review, or CI check when a textual SQL diff
-does not explain the behavioral impact of a query change. It is especially
-useful for data-engineering teams reviewing:
-
-- dbt model changes where a join or filter can change row counts
-- warehouse reports where grouping or aggregation changes the grain
-- incremental pipeline queries where `DISTINCT`, `ORDER BY`, `LIMIT`, or
-  `OFFSET` changes the records consumed downstream
-- generated SQL changes where normalized syntax is easier to compare than
-  formatting or alias changes
-
-The result is a structured object, so a CI integration can fail or annotate a
-review based on `result.risk_level`, inspect `result.changes`, or serialize
-`result.to_dict()` as JSON.
-
-## Real-life data-engineering examples
-
-The `examples/` directory contains runnable before/after pairs. For example:
-
-```powershell
-sql-diff-explainer examples\join_before.sql examples\join_after.sql
-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
-```
-
-These scenarios demonstrate the changes reviewers most often need to discuss:
-
-1. **Outer join to inner join:** changing `LEFT JOIN` to `INNER JOIN` can
-   exclude dimension or fact rows without a match, so the tool reports one
-   semantic join change at high risk.
-2. **Added `WHERE` filter:** adding `WHERE order_status = 'completed'` narrows
-   the population and is reported as a filter change.
-3. **Aggregation or grouping change:** changing `COUNT(*)` to `SUM(revenue)`,
-   or changing the `GROUP BY` grain from customer to customer and day, can
-   change metric meaning and row cardinality.
-4. **`DISTINCT`, ordering, and pagination:** adding `DISTINCT` changes duplicate
-   handling; changing `ORDER BY` changes presentation or deterministic paging;
-   changing `LIMIT`/`OFFSET` changes which rows a downstream consumer receives.
-
-Try the same comparisons from Python:
-
-```python
-from sql_diff_explainer import explain_sql_change
-
-result = explain_sql_change(
-    "SELECT c.id FROM customers c LEFT JOIN orders o ON c.id = o.customer_id",
-    "SELECT c.id FROM customers c INNER JOIN orders o ON c.id = o.customer_id",
-)
-assert result.risk_level == "high"
-for change in result.changes:
-    print(change.category, change.risk, change.description)
-```
-
-## What it catches—and what it cannot know
-
-The analyzer parses both inputs with sqlglot and compares the supported
-`SELECT` structure: projections, joins and join types, `WHERE`, `GROUP BY`,
-aggregate functions, `ORDER BY`, `LIMIT`, `OFFSET`, and `DISTINCT`. It provides
-static risk guidance; it does not execute SQL or connect to a warehouse.
-
-Risk is therefore a useful review signal, not a correctness proof. The tool
-cannot infer table statistics, actual null rates, constraints, query plans,
-cost, freshness, permissions, dialect-specific UDF behavior, or whether a
-business metric is correct. It also does not validate schema availability or
-compare multiple statements in a migration file. Pair its output with
-warehouse tests, representative row-count checks, query-plan review, and
-domain-owner approval.
-
-## Development
-
-This project uses a `src/` layout and requires Python 3.10 or newer.
-
-```powershell
-python -m venv .venv
-.venv\Scripts\Activate.ps1
-python -m pip install -e ".[dev]"
-pytest
-```
-
-## Library usage
-
-```python
-from sql_diff_explainer import explain_sql_change
-
-result = explain_sql_change(
-    "SELECT department, COUNT(*) FROM employees GROUP BY department",
-    "SELECT department, COUNT(*) FROM employees WHERE active = TRUE GROUP BY department",
-)
-print(result.to_dict())
-```
-
-`explain_sql_change` raises `SQLParseError` for invalid SQL and `UnsupportedSQL`
-for non-`SELECT` statements. Pass `dialect="postgres"` (or another sqlglot
-dialect) when parsing dialect-specific syntax.
-
-## CLI
-
-```powershell
-sql-diff-explainer before.sql after.sql
-sql-diff-explainer before.sql after.sql --dialect postgres --format json
-sql-diff-explainer before.sql after.sql --fail-on-risk medium
-sql-diff-explainer before.sql after.sql --format json --fail-on-risk high
-```
-
-`--fail-on-risk` accepts `low`, `medium`, or `high` and exits with status 1 when
-detected overall risk meets or exceeds the chosen threshold. It does not suppress
-the regular text or JSON report. Comparisons with no detected changes exit
-successfully even though their baseline report risk is `low`. JSON output is
-intended for CI and integrations; text output is optimized for human review.
-
-Exit codes:
-
-- `0`: the comparison succeeded and no detected change met the configured
-  threshold (or `--fail-on-risk` was not set).
-- `1`: detected overall risk met or exceeded `--fail-on-risk`.
-- `2`: an input file could not be read or an expected SQL parse/support error
-  occurred.

sql_diff_explainer-0.1.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-sql_diff_explainer/__init__.py,sha256=P-jgWkLNkeuM1kcLChW7rSYWn6EpqOY8K0qMvALxqyA,488
-sql_diff_explainer/cli.py,sha256=XNYIVozEXbjJa_1PXX6ZYmgqxmqHkLHAYNuKaovMCJI,2091
-sql_diff_explainer/core.py,sha256=P9NrPjHGivx-sGlyIyVi7V41x4R2lH3ETC4y8opz_yQ,13265
-sql_diff_explainer-0.1.2.dist-info/METADATA,sha256=0UOgvJOzI3j8gbI64wGVOq1YkGKkNNajipAEGyYJjL4,5863
-sql_diff_explainer-0.1.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-sql_diff_explainer-0.1.2.dist-info/entry_points.txt,sha256=Pu2gG46es25JExzGO58plyLEsFedeCUM-TQnUeLpOlI,67
-sql_diff_explainer-0.1.2.dist-info/licenses/LICENSE,sha256=OJ2eEuGmpMxVb7jSmuVgeDcVHCEOMBkZgLgTlnK5mQQ,1087
-sql_diff_explainer-0.1.2.dist-info/RECORD,,