chore/no-ref: v0.3.0 refactor and open source prep

.github/workflows/ci.yml

@@ -32,5 +32,20 @@ jobs:
       - name: Run pre-commit hooks
         run: poetry run pre-commit run --all-files
 
+      - name: Check version consistency
+        run: |
+          PYPROJECT_VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/' || true)
+          INIT_VERSION=$(grep '^__version__ = ' squawk_alembic/__init__.py | sed 's/__version__ = "\(.*\)"/\1/' || true)
+          if [ -z "$PYPROJECT_VERSION" ] || [ -z "$INIT_VERSION" ]; then
+            echo "::error::Could not parse version from pyproject.toml or __init__.py"
+            exit 1
+          fi
+          if [ "$PYPROJECT_VERSION" != "$INIT_VERSION" ]; then
+            echo "::error::Version mismatch: pyproject.toml ($PYPROJECT_VERSION) != __init__.py ($INIT_VERSION)"
+            echo "Run 'make bump VERSION=x.y.z' to update both files."
+            exit 1
+          fi
+          echo "Versions match: $PYPROJECT_VERSION"
+
       - name: Run tests
         run: poetry run pytest tests/ -v

.gitignore

@@ -1,179 +1,26 @@
-# Byte-compiled / optimized / DLL files
+# Byte-compiled / optimized
 __pycache__/
 *.py[cod]
 *$py.class
 
-# C extensions
-*.so
-
 # Distribution / packaging
-.Python
 build/
-develop-eggs/
 dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
 *.egg-info/
-.installed.cfg
 *.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
 
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
+# Virtual environments
+.venv/
 
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
+# Test / coverage
 .pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/#use-with-ide
-.pdm.toml
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
+.coverage
+htmlcov/
 
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# Editors / OS
 .idea/
-
+.vscode/
 .DS_Store
-.vscode
-.python-version
-
-compare_output/
-export/backup/
-node_modules/
 
-
-.serverless/
-
-# Local files with credentials/secrets
-local_files/
-
-# Claude skills/agents/config
-.claude/
-CLAUDE.md
-.mcp.json
+# Python version
+.python-version

README.md

@@ -4,31 +4,58 @@ A [pre-commit](https://pre-commit.com/) hook that lints SQL in [Alembic](https:/
 
 Squawk operates on raw SQL files, but Alembic migrations are Python. This hook bridges the gap by generating DDL via `alembic upgrade --sql` (offline mode) and passing the complete SQL output to squawk for analysis. This captures all SQL statements a migration produces, including ORM operations like `op.create_index()`, `op.create_table()`, and `op.alter_column()`.
 
-The hook also checks that concurrent index operations (`CONCURRENTLY` in `op.execute()` or `postgresql_concurrently=True` in `op.create_index()` / `op.drop_index()`) are wrapped in `autocommit_block()`.
-
 ## Usage
 
 Add the following to your `.pre-commit-config.yaml`:
 
 ```yaml
 repos:
-    - repo: https://github.com/kintsugi-tax/kintsugi-squawk
-      rev: v0.2.0
+    - repo: https://github.com/kintsugi-tax/squawk-pre-commit
+      rev: v0.3.0
       hooks:
           - id: squawk-alembic
 ```
 
 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).
 
+### Pinning the squawk version
+
+The hook depends on `squawk-cli >= 2.0`. To pin a specific squawk version (matching your local dev dependency, for example), use `additional_dependencies`:
+
+```yaml
+repos:
+    - repo: https://github.com/kintsugi-tax/squawk-pre-commit
+      rev: v0.3.0
+      hooks:
+          - id: squawk-alembic
+            additional_dependencies: ["squawk-cli==2.41.0"]
+```
+
+This overrides the default version and ensures pre-commit uses the exact squawk release you specify.
+
+### 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:
 
 1. Parses `alembic.ini` to find the migrations `versions/` directory
 2. Filters staged files to only those under that directory
-3. Checks for concurrent operations outside `autocommit_block()`
-4. Runs `alembic upgrade --sql` to generate the complete DDL for each migration
-5. Pipes the generated SQL to squawk for linting
+3. Runs `alembic upgrade --sql` to generate the complete DDL for each migration
+4. Pipes the generated SQL to squawk for linting
 
 Merge migrations (where `down_revision` is a tuple) are skipped since they produce no DDL.
 
@@ -55,5 +82,5 @@ To test the hook against a consumer repo locally:
 
 ```bash
 cd /path/to/consumer-repo
-pre-commit try-repo /path/to/kintsugi-squawk squawk-alembic --all-files
+pre-commit try-repo /path/to/squawk-pre-commit squawk-alembic --all-files
 ```

pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "squawk-alembic"
-version = "0.2.0"
+version = "0.3.0"
 description = "Pre-commit hook to lint Alembic migration SQL with squawk"
 packages = [{include = "squawk_alembic"}]
 
 [tool.poetry.dependencies]
 python = ">=3.10"
-squawk-cli = "*"
+squawk-cli = ">=2.0"
 
 [tool.poetry.group.dev.dependencies]
 alembic = "*"

squawk_alembic/__init__.py

@@ -1 +1 @@
-__version__ = "0.2.0"
+__version__ = "0.3.0"