Skip to content

Commit 3f1a06b

Browse files
stephen-kintsugistephen-kintsugi
committed
feat: initial squawk-alembic pre-commit hook
Pre-commit hook that extracts SQL from Alembic migrations and lints with squawk. Auto-detects migrations path from alembic.ini, handles op.execute(), sa.text() wrappers, and checks for CONCURRENTLY operations outside autocommit blocks.
0 parents  commit 3f1a06b

14 files changed

Lines changed: 1520 additions & 0 deletions

‎.gitignore‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
16+
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
share/python-wheels/
24+
*.egg-info/
25+
.installed.cfg
26+
*.egg
27+
MANIFEST
28+
29+
# PyInstaller
30+
# Usually these files are written by a python script from a template
31+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
32+
*.manifest
33+
*.spec
34+
35+
# Installer logs
36+
pip-log.txt
37+
pip-delete-this-directory.txt
38+
39+
# Unit test / coverage reports
40+
htmlcov/
41+
.tox/
42+
.nox/
43+
.coverage
44+
.coverage.*
45+
.cache
46+
nosetests.xml
47+
coverage.xml
48+
*.cover
49+
*.py,cover
50+
.hypothesis/
51+
.pytest_cache/
52+
cover/
53+
54+
# Translations
55+
*.mo
56+
*.pot
57+
58+
# Django stuff:
59+
*.log
60+
local_settings.py
61+
db.sqlite3
62+
db.sqlite3-journal
63+
64+
# Flask stuff:
65+
instance/
66+
.webassets-cache
67+
68+
# Scrapy stuff:
69+
.scrapy
70+
71+
# Sphinx documentation
72+
docs/_build/
73+
74+
# PyBuilder
75+
.pybuilder/
76+
target/
77+
78+
# Jupyter Notebook
79+
.ipynb_checkpoints
80+
81+
# IPython
82+
profile_default/
83+
ipython_config.py
84+
85+
# pyenv
86+
# For a library or package, you might want to ignore these files since the code is
87+
# intended to run in multiple environments; otherwise, check them in:
88+
# .python-version
89+
90+
# pipenv
91+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
93+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
94+
# install all needed dependencies.
95+
#Pipfile.lock
96+
97+
# poetry
98+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
99+
# This is especially recommended for binary packages to ensure reproducibility, and is more
100+
# commonly ignored for libraries.
101+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
102+
#poetry.lock
103+
104+
# pdm
105+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
106+
#pdm.lock
107+
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
108+
# in version control.
109+
# https://pdm.fming.dev/#use-with-ide
110+
.pdm.toml
111+
112+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
113+
__pypackages__/
114+
115+
# Celery stuff
116+
celerybeat-schedule
117+
celerybeat.pid
118+
119+
# SageMath parsed files
120+
*.sage.py
121+
122+
# Environments
123+
.env
124+
.venv
125+
env/
126+
venv/
127+
ENV/
128+
env.bak/
129+
venv.bak/
130+
131+
# Spyder project settings
132+
.spyderproject
133+
.spyproject
134+
135+
# Rope project settings
136+
.ropeproject
137+
138+
# mkdocs documentation
139+
/site
140+
141+
# mypy
142+
.mypy_cache/
143+
.dmypy.json
144+
dmypy.json
145+
146+
# Pyre type checker
147+
.pyre/
148+
149+
# pytype static type analyzer
150+
.pytype/
151+
152+
# Cython debug symbols
153+
cython_debug/
154+
155+
# PyCharm
156+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
157+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
158+
# and can be added to the global gitignore or merged into this file. For a more nuclear
159+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
160+
.idea/
161+
162+
.DS_Store
163+
.vscode
164+
.python-version
165+
166+
compare_output/
167+
export/backup/
168+
node_modules/
169+
170+
171+
.serverless/
172+
173+
# Local files with credentials/secrets
174+
local_files/
175+
176+
# Claude skills/agents/config
177+
.claude/
178+
CLAUDE.md
179+
.mcp.json

‎.pre-commit-config.yaml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# See https://pre-commit.com for more information
2+
# See https://pre-commit.com/hooks.html for more hooks
3+
4+
default_language_version:
5+
python: python3.12
6+
repos:
7+
- repo: https://github.com/pre-commit/pre-commit-hooks
8+
rev: v5.0.0
9+
hooks:
10+
- id: trailing-whitespace
11+
- id: end-of-file-fixer
12+
- id: check-ast
13+
- id: check-merge-conflict
14+
- id: check-symlinks
15+
- id: debug-statements
16+
- id: check-case-conflict
17+
- id: check-vcs-permalinks
18+
- repo: https://github.com/astral-sh/ruff-pre-commit
19+
rev: v0.13.0
20+
hooks:
21+
- id: ruff-format
22+
name: Run ruff code formatting
23+
stages: [ commit ]
24+
- id: ruff
25+
name: Run ruff linting and import sorting
26+
args: [ --fix ]
27+
stages: [ commit ]
28+
- repo: https://github.com/python-poetry/poetry
29+
rev: 2.1.3
30+
hooks:
31+
- id: poetry-check
32+
- repo: https://github.com/facebook/pyrefly-pre-commit
33+
rev: 0.0.1
34+
hooks:
35+
- id: pyrefly-typecheck-system
36+
name: Pyrefly (type checking)
37+
pass_filenames: false
38+
always_run: true

‎.pre-commit-hooks.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
- id: squawk-alembic
2+
name: squawk (alembic migrations)
3+
description: "Lint SQL extracted from Alembic migrations with squawk"
4+
entry: squawk-alembic
5+
language: python
6+
types: [python]
7+
require_serial: true

‎Makefile‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.PHONY: setup_pre_commit run_pre-commit run_unit_tests run_ruff run_pyrefly clean help
2+
3+
# This trick comes from https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
4+
help:
5+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
6+
7+
setup_pre_commit: ## Setup pre-commit hooks
8+
@poetry run pre-commit install
9+
10+
run_pre-commit: ## Run pre-commit hooks
11+
@poetry run pre-commit run --all-files
12+
13+
run_unit_tests: ## Run unit tests
14+
@poetry run pytest tests/ -v
15+
16+
run_ruff: ## Run ruff, the Python linter and code formatter
17+
@poetry run ruff check . --fix
18+
@poetry run ruff format .
19+
20+
run_pyrefly: ## Run pyrefly, a static type checker for Python
21+
@poetry run pyrefly check
22+
23+
clean: ## Clean up the project (e.g., remove cache files)
24+
@find . -type f -name '*.pyc' -delete
25+
@find . -type d -name '__pycache__' -delete

‎README.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Kintsugi Squawk
2+
3+
A [pre-commit](https://pre-commit.com/) hook that lints SQL in [Alembic](https://alembic.sqlalchemy.org/) migrations using [squawk](https://squawkhq.com/), a PostgreSQL migration linter.
4+
5+
Squawk operates on raw SQL files, but Alembic migrations are Python. This hook bridges the gap by extracting SQL from `op.execute()` calls in migration files and passing it to squawk for analysis.
6+
7+
## Usage
8+
9+
Add the following to your `.pre-commit-config.yaml`:
10+
11+
```yaml
12+
repos:
13+
- repo: https://github.com/kintsugi-tax/kintsugi-squawk
14+
rev: v0.1.0
15+
hooks:
16+
- id: squawk-alembic
17+
```
18+
19+
No additional configuration is required. The hook auto-detects your migrations directory by reading `script_location` from `alembic.ini`.
20+
21+
## How It Works
22+
23+
When pre-commit runs, the hook:
24+
25+
1. Parses `alembic.ini` to find the migrations `versions/` directory
26+
2. Filters staged files to only those under that directory
27+
3. Extracts SQL strings from `op.execute()` calls using Python's AST parser
28+
4. Pipes the extracted SQL to squawk for linting
29+
30+
The hook handles common patterns including `op.execute("...")`, `op.execute(sa.text("..."))`, triple-quoted strings, and implicit string concatenation.
31+
32+
ORM-level operations like `op.add_column()` and `op.create_table()` are not linted, since they don't contain raw SQL. These produce safe, predictable DDL that squawk is less likely to flag.
33+
34+
## Squawk Configuration
35+
36+
Squawk reads its configuration from `.squawk.toml` in the consumer repo root. See the [squawk docs](https://squawkhq.com/docs/configuration/) for available options.
37+
38+
## Local Development
39+
40+
**Prerequisites:**
41+
42+
* Python (version 3.12)
43+
* Poetry
44+
45+
**Steps:**
46+
47+
1. Install dependencies: `poetry install`
48+
2. Activate the virtual environment: `source .venv/bin/activate`
49+
3. Install the pre-commit hooks: `pre-commit install`
50+
4. Run tests: `poetry run pytest tests/ -v`
51+
52+
To test the hook against a consumer repo locally:
53+
54+
```bash
55+
cd /path/to/consumer-repo
56+
pre-commit try-repo /path/to/kintsugi-squawk squawk-alembic --all-files
57+
```

0 commit comments

Comments
 (0)