feat: add --diff-branch flag to skip existing migrations

Allows consumers to only lint migration files that don't exist on a
given branch. Makes --all-files safe for repos with older migrations
that have pre-existing squawk violations.

Author: stephen-kintsugi

README.md

@@ -18,6 +18,21 @@ repos:
 
 No additional configuration is required. The hook auto-detects your migrations directory by reading `script_location` from `alembic.ini`. The consumer's `alembic` must be available on PATH (the hook calls it via subprocess).
 
+### Only lint new migrations
+
+To skip migrations that already exist on a branch (useful for repos with existing violations you can't fix immediately), pass `--diff-branch`:
+
+```yaml
+repos:
+    - repo: https://github.com/kintsugi-tax/squawk-pre-commit
+      rev: v0.3.0
+      hooks:
+          - id: squawk-alembic
+            args: [--diff-branch, main]
+```
+
+With this flag, the hook checks whether each migration file exists on the specified branch. Files that already exist are skipped. New files (not yet on the branch) are linted. This makes `pre-commit run --all-files` safe to run in repos where older migrations would fail linting.
+
 ## How It Works
 
 When pre-commit runs, the hook:

squawk_alembic/hook.py

@@ -1,5 +1,6 @@
 """Pre-commit hook that generates DDL via alembic upgrade --sql and lints with squawk."""
 
+import argparse
 import ast
 import configparser
 import os
@@ -126,9 +127,26 @@ def generate_sql(filepath):
     return result.stdout
 
 
+def file_exists_on_branch(filepath, branch):
+    """Check if a file exists on the given git branch."""
+    result = subprocess.run(
+        ["git", "cat-file", "-e", f"{branch}:{filepath}"],
+        capture_output=True,
+    )
+    return result.returncode == 0
+
+
 def main():
-    files = sys.argv[1:]
-    if not files:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--diff-branch",
+        default=None,
+        help="Only lint migration files that don't exist on this branch.",
+    )
+    parser.add_argument("files", nargs="*")
+    args = parser.parse_args()
+
+    if not args.files:
         return 0
 
     migrations_path = find_migrations_path()
@@ -141,12 +159,15 @@ def main():
 
     exit_code = 0
 
-    for filepath in files:
+    for filepath in args.files:
         try:
             Path(filepath).relative_to(migrations_path)
         except ValueError:
             continue
 
+        if args.diff_branch and file_exists_on_branch(filepath, args.diff_branch):
+            continue
+
         sql = generate_sql(filepath)
         if not sql:
             continue

tests/test_main.py

@@ -30,12 +30,16 @@ def make_result(returncode=0, stdout="", stderr=""):
     )()
 
 
-def fake_subprocess(alembic_result=None, squawk_result=None):
+def fake_subprocess(
+    alembic_result=None, squawk_result=None, git_exists_on_branch=False
+):
     """Return a side_effect function that dispatches based on the command."""
     alembic_res = alembic_result or make_result(stdout="CREATE TABLE foo (id int);\n")
     squawk_res = squawk_result or make_result()
 
     def side_effect(cmd, **kwargs):
+        if cmd[0] == "git":
+            return make_result(returncode=0 if git_exists_on_branch else 1)
         if cmd[0] == "alembic":
             return alembic_res
         if cmd[0] == "squawk":
@@ -212,3 +216,79 @@ def upgrade():
         assert main() == 0
         alembic_call = mock_run.call_args_list[0][0][0]
         assert "base:first001" in alembic_call
+
+
+def test_diff_branch_skips_existing_file(repo):
+    path = write_migration(
+        repo,
+        "008_existing.py",
+        """
+        revision = 'exists01'
+        down_revision = 'prev001'
+
+        from alembic import op
+
+        def upgrade():
+            op.execute("CREATE TABLE foo (id int)")
+        """,
+    )
+    with (
+        patch("sys.argv", ["squawk-alembic", "--diff-branch", "main", path]),
+        patch(
+            "subprocess.run",
+            side_effect=fake_subprocess(git_exists_on_branch=True),
+        ) as mock_run,
+    ):
+        assert main() == 0
+        # Only the git cat-file call should happen, no alembic or squawk
+        assert mock_run.call_count == 1
+        assert mock_run.call_args_list[0][0][0][0] == "git"
+
+
+def test_diff_branch_lints_new_file(repo):
+    path = write_migration(
+        repo,
+        "009_new.py",
+        """
+        revision = 'new001'
+        down_revision = 'prev001'
+
+        from alembic import op
+
+        def upgrade():
+            op.execute("CREATE TABLE foo (id int)")
+        """,
+    )
+    with (
+        patch("sys.argv", ["squawk-alembic", "--diff-branch", "main", path]),
+        patch(
+            "subprocess.run",
+            side_effect=fake_subprocess(git_exists_on_branch=False),
+        ) as mock_run,
+    ):
+        assert main() == 0
+        # git cat-file + alembic + squawk = 3 calls
+        assert mock_run.call_count == 3
+
+
+def test_without_diff_branch_lints_all(repo):
+    path = write_migration(
+        repo,
+        "010_all.py",
+        """
+        revision = 'all001'
+        down_revision = 'prev001'
+
+        from alembic import op
+
+        def upgrade():
+            op.execute("CREATE TABLE foo (id int)")
+        """,
+    )
+    with (
+        patch("sys.argv", ["squawk-alembic", path]),
+        patch("subprocess.run", side_effect=fake_subprocess()) as mock_run,
+    ):
+        assert main() == 0
+        # No git call, just alembic + squawk = 2 calls
+        assert mock_run.call_count == 2