ci: migrate commit validation to prek+gitlint and standardize CI tool setup

.github/workflows/conventional-commits.yml

@@ -6,30 +6,31 @@ permissions:
   contents: read
 
 jobs:
-  commitlint:
+  conventional-commits:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-      - name: Setup node
-        uses: actions/setup-node@v6
+      - name: Set up mise
+        uses: jdx/mise-action@v3
         with:
-          node-version: lts/*
-          cache: npm
-      - name: Install commitlint
-        run: npm install -D @commitlint/cli @commitlint/config-conventional
+          install: true
+          cache: true
+          cache_key_prefix: mise-v1-prek
       - name: Print versions
         run: |
           git --version
-          node --version
-          npm --version
-          npx commitlint --version
+          uv --version
 
-      - name: Validate current commit (last commit) with commitlint
+      - name: Validate current commit range
         if: github.event_name == 'push'
-        run: npx commitlint --last --verbose
+        env:
+          PREK_COMMIT_RANGE: HEAD~1..HEAD
+        run: uvx --from prek==0.3.4 --with gitlint==0.19.1 prek run conventional-commits-ci --stage manual
 
-      - name: Validate PR commits with commitlint
+      - name: Validate PR commit range
         if: github.event_name == 'pull_request'
-        run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
+        env:
+          PREK_COMMIT_RANGE: ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}
+        run: uvx --from prek==0.3.4 --with gitlint==0.19.1 prek run conventional-commits-ci --stage manual

.github/workflows/python-package.yml

@@ -13,26 +13,22 @@ jobs:
   build:
 
     runs-on: macos-latest
+    env:
+      PYTHON_VERSION: ${{ matrix.python-version }}
     strategy:
       fail-fast: false
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14",]
 
     steps:
     - uses: actions/checkout@v6
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v6
-      with:
-        python-version: ${{ matrix.python-version }}      
-    - uses: yezz123/setup-uv@v4 
-      with:
-        uv-version: "0.9.3"
     - name: Set up mise
       uses: jdx/mise-action@v3
       with:
         install: true
         cache: true
         cache_key_prefix: mise-v1-py${{ matrix.python-version }}
+        install_args: python uv go
     - name: Install Poppler
       run: brew install poppler
     - name: Install pdfocr

.github/workflows/release.yml

@@ -11,6 +11,7 @@ jobs:
     permissions:
       contents: read
     env:
+      PYTHON_VERSION: "3.11"
       dist_artifacts_name: dist
       dist_artifacts_dir: dist
       lock_file_artifact: uv.lock
@@ -23,8 +24,13 @@ jobs:
       - name: Setup | Force correct release branch on workflow sha
         run: git checkout -B ${{ github.ref_name }}
 
-      - name: Setup | Install uv
-        uses: asdf-vm/actions/install@1902764435ca0dd2f3388eea723a4f92a4eb8302  # v4.0.2
+      - name: Setup | Install mise tools
+        uses: jdx/mise-action@v3
+        with:
+          install: true
+          cache: true
+          cache_key_prefix: mise-v1-release-build
+          install_args: python uv
 
       - name: Install poppler (macOS)
         run: brew install poppler
@@ -68,6 +74,8 @@ jobs:
   test-e2e:
     needs: build
     runs-on: macos-latest
+    env:
+      PYTHON_VERSION: "3.11"
     steps:
       - name: Setup | Checkout Repository
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8  # v6.0.1
@@ -86,8 +94,13 @@ jobs:
       - name: Install Poppler (macOS)
         run: brew install poppler
 
-      - name: Setup | Install uv
-        uses: asdf-vm/actions/install@1902764435ca0dd2f3388eea723a4f92a4eb8302  # v4.0.2
+      - name: Setup | Install mise tools
+        uses: jdx/mise-action@v3
+        with:
+          install: true
+          cache: true
+          cache_key_prefix: mise-v1-release-test
+          install_args: python uv
 
       - name: Setup | Install Python & Project dependencies
         run: uv sync --extra test
@@ -107,6 +120,8 @@ jobs:
     needs:
       - build
       - test-e2e
+    env:
+      PYTHON_VERSION: "3.11"
 
     if: ${{ needs.build.outputs.new-release-detected == 'true' }}
 
@@ -126,8 +141,13 @@ jobs:
       - name: Setup | Force release branch to be at workflow sha
         run: git reset --hard ${{ github.sha }}
 
-      - name: Setup | Install uv
-        uses: asdf-vm/actions/install@1902764435ca0dd2f3388eea723a4f92a4eb8302  # v4.0.2
+      - name: Setup | Install mise tools
+        uses: jdx/mise-action@v3
+        with:
+          install: true
+          cache: true
+          cache_key_prefix: mise-v1-release-publish
+          install_args: python uv
 
       - name: Setup | Install Python & Project dependencies
         run: uv sync --extra build --extra dev
@@ -190,4 +210,4 @@ jobs:
         with:
           packages-dir: dist
           print-hash: true
-          verbose: true
+          verbose: true

.gitlint

@@ -0,0 +1,12 @@
+[general]
+contrib = CT1
+ignore = B6
+
+[contrib-title-conventional-commits]
+types = fix,feat,chore,docs,style,refactor,perf,test,revert,ci,build
+
+[body-max-line-length]
+line-length = 150
+
+[title-max-length]
+line-length = 100

AGENTS.md

@@ -145,7 +145,7 @@ mise run lint && mise run typecheck && mise run test
 ```
 
 ## Commit and PR Rules
-- Conventional Commits are enforced in CI (`commitlint`)
+- Conventional Commits are enforced in CI (`prek` + `gitlint`)
 - Common prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
 - Commit body max line length rule: `150`
 

CONTRIBUTING.md

@@ -146,7 +146,7 @@ consumers of your library:
 1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in Semantic Versioning).
 1. **BREAKING CHANGE:** a commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in Semantic Versioning).
 A BREAKING CHANGE can be part of commits of any _type_.
-1. _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `build:`, `chore:`,
+1. _types_ other than `fix:` and `feat:` are allowed, for example [gitlint CT1](https://jorisroovers.com/gitlint/latest/rules/contrib_rules/#ct1-contrib-title-conventional-commits) (based on the [Conventional Commits convention](https://www.conventionalcommits.org/)) recommends `build:`, `chore:`,
   `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others.
 1. _footers_ other than `BREAKING CHANGE: <description>` may be provided and follow a convention similar to
   [git trailer format](https://git-scm.com/docs/git-interpret-trailers).

mise.toml

@@ -39,5 +39,12 @@ depends = ["lint", "typecheck", "test"]
 description = "Run check + format"
 depends = ["check", "format"]
 
+[tasks.commit-check]
+description = "Run Conventional Commit checks via prek"
+depends = ["install"]
+run = "uv run prek run conventional-commits-ci --stage manual"
+
 [tools]
+python = "{{ get_env(name='PYTHON_VERSION', default='3.11') }}"
+uv = "0.9.18"
 go = "1.25"