build(commitlint): enforce Conventional Commit messages locally and in CI

.githooks/commit-msg

@@ -0,0 +1,42 @@
+#!/bin/sh
+# Commit-message lint: the SAME tool CI runs — commitlint over
+# commitlint.config.mjs — executed through the docker compose `node` service,
+# so contributors need docker but no host Node toolchain.
+#
+# Installed by `composer install` via `git config core.hooksPath .githooks`.
+# The message is piped on stdin (comment lines stripped, as git would on
+# commit), so no path mapping into the container is needed and the hook works
+# from worktrees too. node_modules is (re)installed from the lockfile whenever
+# it's missing or stale, so the local commitlint always matches the pinned one.
+
+msg_file="$1"
+
+if ! command -v docker > /dev/null 2>&1; then
+    echo "commit-msg: docker is required to lint the commit message (compose service 'node')." >&2
+    echo "  rules: commitlint.config.mjs (Conventional Commits) — CI enforces the same check." >&2
+    exit 1
+fi
+
+# `command -v docker` isn't enough: this hook runs `docker compose run`, which
+# needs the Compose v2 plugin. Without it, Docker prints its own cryptic
+# "'compose' is not a docker command" — surface a useful message instead.
+if ! docker compose version > /dev/null 2>&1; then
+    echo "commit-msg: the Docker Compose v2 plugin is required ('docker compose' is unavailable)." >&2
+    echo "  rules: commitlint.config.mjs (Conventional Commits) — CI enforces the same check." >&2
+    exit 1
+fi
+
+top=$(git rev-parse --show-toplevel)
+
+# Reinstall when node_modules is absent OR the lockfile is newer than the
+# installed binary — a version bump a collaborator pulls in updates
+# package-lock.json but leaves node_modules untouched, and a stale local
+# commitlint would silently disagree with CI. `npm ci` is otherwise skipped so
+# the common case (already installed) stays fast.
+sed -e 's/\r$//' -e '/^#/d' "$msg_file" \
+    | docker compose --project-directory "$top" run --rm -T --no-deps node sh -c '
+        if [ ! -x node_modules/.bin/commitlint ] || [ package-lock.json -nt node_modules/.bin/commitlint ]; then
+            npm ci --no-audit --no-fund --loglevel=error
+        fi
+        exec node_modules/.bin/commitlint
+    '

.github/workflows/commitlint.yml

@@ -0,0 +1,38 @@
+name: Commitlint
+
+# Gate every PR on Conventional Commit messages. Same tool, same version, same
+# config as the local .githooks/commit-msg hook: commitlint pinned by
+# package-lock.json, rules in commitlint.config.mjs.
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  commitlint:
+    name: Conventional commit messages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # commitlint needs the full PR range, not a shallow tip.
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          # Keep in step with the compose `node` service image.
+          node-version: 24
+          cache: npm
+      - name: Install commitlint (lockfile-pinned)
+        run: npm ci --no-audit --no-fund
+      - name: Lint PR commit messages
+        run: >
+          npx --no-install commitlint
+          --from ${{ github.event.pull_request.base.sha }}
+          --to ${{ github.event.pull_request.head.sha }}
+          --verbose

.gitignore

@@ -13,3 +13,4 @@
 /core/.xphp-cache/
 docker-compose.override.yml
 .phpunit.result.cache
+node_modules/

CONTRIBUTING.md

@@ -1,5 +1,30 @@
 # Contributing
 
+## Commit messages
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org):
+
+```
+type(scope): lowercase subject
+```
+
+Types: `build` `chore` `ci` `docs` `feat` `fix` `perf` `refactor` `revert`
+`style` `test`. The scope is the component the change lives in
+(`monomorphize`, `specializer`, `parser`, `cli`, ...); bare `type:` is fine
+for cross-cutting changes. Examples from the history:
+
+```
+feat(monomorphize): ground enclosing-param method turbofish per class specialization
+fix(cli): locate Composer autoloader when installed as a dependency
+docs: refresh docs/ tree with syntax tour, caveats, errors
+```
+
+CI rejects a PR whose commits don't conform: `commitlint` (pinned by
+`package-lock.json`) over `commitlint.config.mjs`. Locally, `composer
+install` wires up a `commit-msg` hook (`.githooks/`) that runs the **same
+tool** through the docker compose `node` service at commit time — docker is
+required, a host Node toolchain is not.
+
 ## Test
 
 ```bash

commitlint.config.mjs

@@ -0,0 +1,15 @@
+// Commit-message rules: Conventional Commits (https://www.conventionalcommits.org).
+// One rule set, one tool, two entry points:
+//   - locally:  .githooks/commit-msg runs commitlint through the docker compose
+//               `node` service (installed by `composer install`)
+//   - in CI:    .github/workflows/commitlint.yml runs the same lockfile-pinned
+//               commitlint over every PR commit
+//
+// The stock preset already matches this repo's history:
+//   type(scope): lowercase subject
+// with types build/chore/ci/docs/feat/fix/perf/refactor/revert/style/test, an
+// optional free-form scope (monomorphize, specializer, parser, cli, ...), a
+// 100-char header cap, and merge/revert/fixup subjects ignored.
+export default {
+    extends: ['@commitlint/config-conventional'],
+};

composer.json

@@ -51,5 +51,13 @@
         "allow-plugins": {
             "infection/extension-installer": true
         }
+    },
+    "scripts": {
+        "post-install-cmd": "@git:hooks",
+        "post-update-cmd": "@git:hooks",
+        "git:hooks": "git rev-parse --git-dir > /dev/null 2>&1 && git config core.hooksPath .githooks || true"
+    },
+    "scripts-descriptions": {
+        "git:hooks": "Point git at the tracked .githooks/ directory (commit-msg lint); no-op outside a git checkout."
     }
 }

docker-compose.yml

@@ -22,5 +22,20 @@ services:
       service: php
     entrypoint: [ "/opt/app/bin/xphp" ]
 
+  # Node runtime for commit-message linting: the .githooks/commit-msg hook runs
+  # commitlint through this service, so contributors need docker but no host
+  # Node toolchain — and local linting uses the exact tool CI runs. One-shot:
+  #   docker compose run --rm node npx commitlint --help
+  # Runs commitlint for the commit-msg hook and CI. Behind a profile so a bare
+  # `docker compose up` doesn't start it; the hook targets it explicitly with
+  # `docker compose run node`, which starts a profiled service on demand and
+  # supplies its own command (no keepalive needed).
+  node:
+    image: node:24-alpine
+    working_dir: /opt/app
+    volumes:
+      - ./:/opt/app
+    profiles: [ "commitlint" ]
+
 volumes:
   composer_cache: ~