chore: open source readiness improvements

* add LICENSE (MIT), CONTRIBUTING.md, authors, keywords, classifiers
* merge auto-tag workflow into ci.yml gated on lint-and-test
* fix CI expression injection by moving tag to env block
* pin snok/install-poetry to SHA, bump pyrefly-pre-commit to 0.53.0
* tighten branch regex to reject leading hyphens and ".." traversal
* handle missing git binary in validate_branch
* fail the run when alembic upgrade --sql errors (GenerateSqlError)
* document env.py execution and DATABASE_URL fallback in README
* rename README title to squawk-pre-commit
* add .ruff_cache/ to .gitignore

Author: stephen-kintsugi

.github/workflows/auto-tag.yml

@@ -20,7 +20,7 @@ jobs:
           python-version: '3.12'
 
       - name: Install Poetry
-        uses: snok/install-poetry@v1
+        uses: snok/install-poetry@76e04a911780d5b312d89783f7b1cd627778900a # v1.4.1
         with:
           version: latest
           virtualenvs-create: true
@@ -49,3 +49,60 @@ jobs:
 
       - name: Run tests
         run: poetry run pytest tests/ -v
+
+  auto-tag:
+    needs: lint-and-test
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      tag: ${{ steps.tag.outputs.tag }}
+      created: ${{ steps.tag.outputs.created }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create tag if needed
+        id: tag
+        run: |
+          VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          TAG="v${VERSION}"
+
+          echo "Detected version: $VERSION"
+          echo "Tag: $TAG"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists. Nothing to do."
+            echo "created=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "Creating and pushing tag $TAG"
+          git tag "$TAG"
+          git push origin "$TAG"
+          echo "created=true" >> "$GITHUB_OUTPUT"
+
+  release:
+    needs: auto-tag
+    if: needs.auto-tag.outputs.created == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ needs.auto-tag.outputs.tag }}
+        run: |
+          gh release create "$TAG" \
+            --title "Release $TAG" \
+            --generate-notes

.github/workflows/ci.yml

@@ -12,6 +12,9 @@ dist/
 # Virtual environments
 .venv/
 
+# Linting
+.ruff_cache/
+
 # Test / coverage
 .pytest_cache/
 .coverage

.gitignore

@@ -30,7 +30,7 @@ repos:
       hooks:
           - id: poetry-check
     - repo: https://github.com/facebook/pyrefly-pre-commit
-      rev: 0.0.1
+      rev: 0.53.0
       hooks:
         - id: pyrefly-typecheck-system
           name: Pyrefly (type checking)

.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+# Contributing
+
+We welcome contributions to squawk-pre-commit. Here's how to get started.
+
+## Development Setup
+
+1. Clone the repo and install dependencies:
+
+```bash
+git clone https://github.com/kintsugi-tax/squawk-pre-commit.git
+cd squawk-pre-commit
+poetry install
+```
+
+2. Install pre-commit hooks:
+
+```bash
+pre-commit install
+```
+
+3. Run the test suite:
+
+```bash
+poetry run pytest tests/ -v
+```
+
+## Submitting Changes
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes and add tests where appropriate
+3. Ensure all tests pass and pre-commit hooks are clean
+4. Open a pull request against `main`
+
+## Reporting Issues
+
+Open an issue on [GitHub](https://github.com/kintsugi-tax/squawk-pre-commit/issues) with a clear description of the problem and steps to reproduce.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kintsugi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE

@@ -1,4 +1,4 @@
-# Kintsugi Squawk
+# squawk-pre-commit
 
 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.
 
@@ -59,6 +59,13 @@ When pre-commit runs, the hook:
 
 Merge migrations (where `down_revision` is a tuple) are skipped since they produce no DDL.
 
+## Known Limitations
+
+* The hook runs `alembic upgrade --sql`, which executes your project's `env.py` in offline mode. No database connection is made, but the Python code in `env.py` does run.
+* If `DATABASE_URL` is not set, the hook provides a dummy fallback (`postgresql://localhost/lint`) so alembic's offline mode can generate SQL without a real connection string.
+* If `alembic upgrade --sql` fails for a migration (e.g. due to missing dependencies or env configuration), the hook prints the error to stderr and fails the run.
+* Merge migrations (where `down_revision` is a tuple) produce no DDL and are always skipped.
+
 ## Squawk Configuration
 
 Squawk reads its configuration from `.squawk.toml` in the consumer repo root. See the [squawk docs](https://squawkhq.com/docs/configuration/) for available options.
@@ -67,7 +74,7 @@ Squawk reads its configuration from `.squawk.toml` in the consumer repo root. Se
 
 **Prerequisites:**
 
-* Python (version 3.12)
+* Python 3.10+ (3.12 recommended for development)
 * Poetry
 * squawk-cli (`pip install squawk-cli`)
 
@@ -78,6 +85,8 @@ Squawk reads its configuration from `.squawk.toml` in the consumer repo root. Se
 3. Install the pre-commit hooks: `pre-commit install`
 4. Run tests: `poetry run pytest tests/ -v`
 
+Some integration tests in `tests/test_squawk_config.py` require `squawk` on PATH and are automatically skipped if it is not installed.
+
 To test the hook against a consumer repo locally:
 
 ```bash

README.md

@@ -7,6 +7,22 @@ name = "squawk-alembic"
 version = "0.3.0"
 description = "Pre-commit hook to lint Alembic migration SQL with squawk"
 packages = [{include = "squawk_alembic"}]
+readme = "README.md"
+homepage = "https://www.trykintsugi.com/"
+repository = "https://github.com/kintsugi-tax/squawk-pre-commit"
+authors = ["Kintsugi <engineering@trykintsugi.com>"]
+license = "MIT"
+keywords = ["pre-commit", "squawk", "alembic", "postgresql", "migration", "linter"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Database",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
 
 [tool.poetry.dependencies]
 python = ">=3.10"

pyproject.toml

@@ -10,7 +10,7 @@
 from configparser import ConfigParser, NoOptionError, NoSectionError
 from pathlib import Path
 
-_BRANCH_RE = re.compile(r"^[a-zA-Z0-9._/\-]+$")
+_BRANCH_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._/\-]*$")
 
 
 def find_migrations_path():
@@ -90,8 +90,16 @@ def extract_revision_info(filepath):
     )
 
 
+class GenerateSqlError(Exception):
+    """Raised when alembic upgrade --sql fails."""
+
+
 def generate_sql(filepath):
-    """Run alembic upgrade --sql to generate the complete DDL for a migration."""
+    """Run alembic upgrade --sql to generate the complete DDL for a migration.
+
+    Returns the SQL string, or None if the file should be skipped (merge migration,
+    unparseable revision). Raises GenerateSqlError if alembic fails.
+    """
     info = extract_revision_info(filepath)
     if info is None:
         return None
@@ -114,34 +122,34 @@ def generate_sql(filepath):
             env=env,
         )
     except FileNotFoundError:
-        print(
-            "squawk-alembic: alembic not found. Ensure alembic is installed in your environment.",
-            file=sys.stderr,
+        raise GenerateSqlError(
+            "squawk-alembic: alembic not found. Ensure alembic is installed in your environment."
         )
-        return None
 
     if result.returncode != 0:
-        print(
-            f"squawk-alembic: alembic upgrade --sql failed for {filepath}:\n{result.stderr}",
-            file=sys.stderr,
+        raise GenerateSqlError(
+            f"squawk-alembic: alembic upgrade --sql failed for {filepath}:\n{result.stderr}"
         )
-        return None
 
     return result.stdout
 
 
 def validate_branch(branch):
     """Validate that a branch name is safe and exists in git."""
-    if not _BRANCH_RE.match(branch):
+    if not _BRANCH_RE.match(branch) or ".." in branch:
         print(
             f"squawk-alembic: invalid branch name: {branch!r}",
             file=sys.stderr,
         )
         return False
-    result = subprocess.run(
-        ["git", "rev-parse", "--verify", branch],
-        capture_output=True,
-    )
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--verify", branch],
+            capture_output=True,
+        )
+    except FileNotFoundError:
+        print("squawk-alembic: git not found", file=sys.stderr)
+        return False
     if result.returncode != 0:
         print(
             f"squawk-alembic: branch '{branch}' not found in git",
@@ -195,7 +203,13 @@ def main():
         if args.diff_branch and file_exists_on_branch(filepath, args.diff_branch):
             continue
 
-        sql = generate_sql(filepath)
+        try:
+            sql = generate_sql(filepath)
+        except GenerateSqlError as exc:
+            print(str(exc), file=sys.stderr)
+            exit_code = 1
+            continue
+
         if not sql:
             continue