feat: add diff() and diff_files() functions (#253)

Add functions that return the set of statements that differ between
two SQL strings or files, using symmetric difference. This provides
more detail than the boolean compare() function.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jd

sql_compare/__init__.py

@@ -52,9 +52,19 @@ def compare_files(first_file: pathlib.Path, second_file: pathlib.Path) -> bool:
     return compare(first_file.read_text(), second_file.read_text())
 
 
+def diff_files(first_file: pathlib.Path, second_file: pathlib.Path) -> set[Statement]:
+    """Return the set of statements that differ between two SQL files."""
+    return diff(first_file.read_text(), second_file.read_text())
+
+
 def compare(first_sql: str, second_sql: str) -> bool:
     """Compare two SQL strings."""
-    return _parse_statements(first_sql) == _parse_statements(second_sql)
+    return not diff(first_sql, second_sql)
+
+
+def diff(first_sql: str, second_sql: str) -> set[Statement]:
+    """Return the set of statements that differ between two SQL strings."""
+    return _parse_statements(first_sql) ^ _parse_statements(second_sql)
 
 
 def get_diff(

tests/test_sql_compare.py

@@ -102,6 +102,7 @@
 )
 def test_compare_eq(first_sql: str, second_sql: str) -> None:
     assert sql_compare.compare(first_sql, second_sql)
+    assert not sql_compare.diff(first_sql, second_sql)
 
 
 @pytest.mark.parametrize(
@@ -164,6 +165,7 @@ def test_compare_eq(first_sql: str, second_sql: str) -> None:
 )
 def test_compare_neq(first_sql: str, second_sql: str) -> None:
     assert not sql_compare.compare(first_sql, second_sql)
+    assert sql_compare.diff(first_sql, second_sql)
 
 
 @pytest.mark.parametrize(