chore: v0.3.3 code quality, CI improvements, and test coverage

Author: stephen-kintsugi

.github/actions/setup-python-poetry/action.yml

@@ -0,0 +1,44 @@
+name: Setup Python Environment
+description: Setup Python, Poetry, and cache dependencies
+
+inputs:
+  python-version:
+    description: Python version
+    required: false
+    default: '3.12'
+  install-dependencies:
+    description: Whether to install project dependencies
+    required: false
+    default: 'true'
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install Poetry
+      uses: snok/install-poetry@76e04a911780d5b312d89783f7b1cd627778900a # v1.4.1
+      with:
+        version: "2.1.3"
+        virtualenvs-create: true
+        virtualenvs-in-project: true
+        installer-parallel: true
+
+    - name: Cache virtualenv
+      if: inputs.install-dependencies == 'true'
+      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+      with:
+        path: .venv
+        key: ${{ runner.os }}-py${{ inputs.python-version }}-poetry-${{ hashFiles('**/poetry.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-py${{ inputs.python-version }}-poetry-
+
+    - name: Install dependencies
+      if: inputs.install-dependencies == 'true'
+      shell: bash
+      run: |
+        poetry sync -n
+        poetry env info -n

.github/workflows/ci.yml

@@ -6,40 +6,57 @@ on:
   pull_request:
     branches: [main]
 
+concurrency:
+  group: ci-${{ github.head_ref || github.sha }}
+  cancel-in-progress: true
+
 jobs:
   lint-and-test:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      code_changed: ${{ steps.changes.outputs.code_changed }}
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          python-version: '3.12'
+          fetch-depth: 0
 
-      - name: Install Poetry
-        uses: snok/install-poetry@76e04a911780d5b312d89783f7b1cd627778900a # v1.4.1
-        with:
-          version: "2.1.3"
-          virtualenvs-create: true
-          virtualenvs-in-project: true
+      - name: Detect code changes
+        id: changes
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE="${{ github.event.pull_request.base.sha }}"
+          else
+            BASE="${{ github.event.before }}"
+          fi
+          # Only track files that affect the distributed package.
+          # Test, CI, and doc changes do not require a version bump or release.
+          CHANGED=$(git diff --name-only "$BASE" HEAD -- \
+            'squawk_alembic/' \
+            'pyproject.toml' \
+            '.pre-commit-hooks.yaml')
+          if [ -n "$CHANGED" ]; then
+            echo "code_changed=true" >> "$GITHUB_OUTPUT"
+            echo "Code files changed:"
+            echo "$CHANGED"
+          else
+            echo "code_changed=false" >> "$GITHUB_OUTPUT"
+            echo "Only non-code files changed, skipping version check and release."
+          fi
 
-      - name: Install dependencies
-        run: poetry install --no-interaction
+      - name: Setup Python and Poetry
+        uses: ./.github/actions/setup-python-poetry
 
       - name: Run pre-commit hooks
         run: poetry run pre-commit run --all-files
 
       - name: Check version consistency
+        if: steps.changes.outputs.code_changed == 'true'
         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
+          PYPROJECT_VERSION=$(poetry version -s)
+          INIT_VERSION=$(python -c "import squawk_alembic; print(squawk_alembic.__version__)")
           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."
@@ -49,7 +66,7 @@ jobs:
 
           if [ "${{ github.event_name }}" = "pull_request" ]; then
             git fetch origin main --depth=1
-            MAIN_VERSION=$(git show origin/main:pyproject.toml | grep '^version = ' | sed 's/version = "\(.*\)"/\1/' || true)
+            MAIN_VERSION=$(git show origin/main:pyproject.toml | python -c "import sys, tomllib; print(tomllib.loads(sys.stdin.read())['tool']['poetry']['version'])" || true)
             if [ -z "$MAIN_VERSION" ]; then
               echo "::warning::Could not determine version on main, skipping version bump check"
             elif [ "$PYPROJECT_VERSION" = "$MAIN_VERSION" ]; then
@@ -64,8 +81,9 @@ jobs:
 
   auto-tag:
     needs: lint-and-test
-    if: github.event_name == 'push'
+    if: github.event_name == 'push' && needs.lint-and-test.outputs.code_changed == 'true'
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     permissions:
       contents: write
     outputs:
@@ -74,14 +92,19 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
 
+      - name: Setup Python and Poetry
+        uses: ./.github/actions/setup-python-poetry
+        with:
+          install-dependencies: 'false'
+
       - name: Create tag if needed
         id: tag
         run: |
-          VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          VERSION=$(poetry version -s)
           TAG="v${VERSION}"
 
           echo "Detected version: $VERSION"
@@ -103,12 +126,13 @@ jobs:
     needs: auto-tag
     if: needs.auto-tag.outputs.created == 'true'
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     permissions:
       contents: write
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Create GitHub Release
         env:

README.md

@@ -11,7 +11,7 @@ Add the following to your `.pre-commit-config.yaml`:
 ```yaml
 repos:
     - repo: https://github.com/kintsugi-tax/squawk-pre-commit
-      rev: v0.3.0
+      rev: v0.3.3
       hooks:
           - id: squawk-alembic
 ```
@@ -25,7 +25,7 @@ The hook depends on `squawk-cli >= 2.0`. To pin a specific squawk version (match
 ```yaml
 repos:
     - repo: https://github.com/kintsugi-tax/squawk-pre-commit
-      rev: v0.3.0
+      rev: v0.3.3
       hooks:
           - id: squawk-alembic
             additional_dependencies: ["squawk-cli==2.41.0"]
@@ -40,7 +40,7 @@ To skip migrations that already exist on a branch (useful for repos with existin
 ```yaml
 repos:
     - repo: https://github.com/kintsugi-tax/squawk-pre-commit
-      rev: v0.3.0
+      rev: v0.3.3
       hooks:
           - id: squawk-alembic
             args: [--diff-branch, main]
@@ -92,6 +92,16 @@ Squawk reads its configuration from `.squawk.toml` in the consumer repo root. Se
 
 Some integration tests in `tests/test_squawk_config.py` require `squawk` on PATH and are automatically skipped if it is not installed.
 
+**Versioning:**
+
+PRs that change package files (`squawk_alembic/`, `pyproject.toml`, `.pre-commit-hooks.yaml`) must include a version bump. CI enforces this. To bump:
+
+```bash
+make bump VERSION=0.3.3
+```
+
+This updates both `pyproject.toml` and `squawk_alembic/__init__.py`. On merge to main, CI automatically creates a git tag and GitHub release from the new version. Changes to tests, docs, or CI config do not require a version bump.
+
 To test the hook against a consumer repo locally:
 
 ```bash