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

[math3usmartins]

Commit subjects have followed the Conventional Commits pattern
(type(scope): lowercase subject) by convention only; nothing rejected a
stray unprefixed message. This adopts commitlint as the single
enforcement tool, with one rule set and one pinned version shared by
both entry points:

• Rules: commitlint.config.mjs, the stock config-conventional preset,
  which already matches the repo history (types build/chore/ci/docs/
  feat/fix/perf/refactor/revert/style/test, optional scope, lowercase
  subject, 100-char header, merge/revert subjects ignored).

• Versions: pinned by package.json + package-lock.json (private,
  dev-only; the PHP package proper stays in composer.json).

• Local: composer install wires up the tracked .githooks/commit-msg
  hook via core.hooksPath. The hook pipes the message (comment lines
  stripped, worktree-safe) into commitlint through a new docker compose
  node service (node:24-alpine), so contributors need docker but no
  host Node toolchain.

• CI: a new Commitlint workflow runs the same lockfile-pinned
  commitlint over the full PR commit range. It is the authoritative
  check backing the local hook, which can be bypassed with --no-verify.

CONTRIBUTING documents the format with real examples from the history.

[math3usmartins]

Too many files changed for review. (123 files found, 100 file limit)

Bypass the limit by tagging @greptile-apps to review.

@greptile-apps

[greptile-apps]

Greptile Summary

This PR introduces commitlint as the single Conventional Commits enforcement tool, wired up through two entry points that share the same lockfile-pinned version and commitlint.config.mjs config.

• Local hook (.githooks/commit-msg): installed by composer install via core.hooksPath; runs commitlint through the new node:24-alpine Docker Compose service (behind the commitlint profile so docker compose up never starts it accidentally), with a lockfile-mtime staleness guard that triggers npm ci when the binary is absent or package-lock.json has been updated by a collaborator.
• CI workflow (.github/workflows/commitlint.yml): lints the full PR commit range using fetch-depth: 0 and npm ci for deterministic, lockfile-pinned installs — the authoritative gate that backs the bypassable local hook.
• Documentation: CONTRIBUTING.md is updated with the format spec and concrete examples drawn from the project history.

Confidence Score: 5/5

Safe to merge — all changes are additive tooling infrastructure with no impact on the PHP package or runtime behaviour.

The hook, CI workflow, and Compose service are self-contained and well-guarded: docker + compose-v2 are checked before use, the lockfile staleness test correctly detects collaborator version bumps, the commitlint Compose profile prevents accidental startup on docker compose up, and CI uses fetch-depth: 0 plus npm ci for deterministic installs. Previous review concerns are all addressed in this revision.

Files Needing Attention: No files require special attention.

Important Files Changed

Filename	Overview
.githooks/commit-msg	New commit-msg hook that pipes cleaned message to commitlint via docker compose run; includes docker/compose-v2 preflight checks and a lockfile-mtime staleness guard to keep local version in sync with CI.
.github/workflows/commitlint.yml	New CI workflow that runs commitlint over the full PR commit range using fetch-depth: 0, npm ci for lockfile-pinned install, and npx --no-install to prevent ad-hoc downloads.
docker-compose.yml	Adds a node:24-alpine service behind the commitlint profile so it is never started by bare docker compose up; the hook reaches it via docker compose run which starts profiled services on demand.
composer.json	Adds post-install-cmd/post-update-cmd that configure core.hooksPath .githooks with a git-repo guard and `
commitlint.config.mjs	Minimal config extending the stock @commitlint/config-conventional preset; shared by both the local hook and CI.
package.json	Adds @commitlint/cli and @commitlint/config-conventional as dev dependencies; npm ci is always used so the ^ range in package.json doesn't affect installed versions.
package-lock.json	Generated lockfile pinning both commitlint packages at 19.8.1; committed so npm ci produces identical installs locally and in CI.
.gitignore	Adds node_modules/ exclusion to prevent the container-installed packages from being accidentally committed.
CONTRIBUTING.md	Documents the Conventional Commits format with real examples from the repo history, and explains the two-entry-point enforcement (local hook + CI).

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Git as Git
    participant Hook as .githooks/commit-msg
    participant Docker as Docker Compose (node service)
    participant CL as commitlint

    Dev->>Git: git commit -m "feat: ..."
    Git->>Hook: invoke with commit-msg tempfile
    Hook->>Hook: check docker binary
    Hook->>Hook: check docker compose v2 plugin
    Hook->>Hook: git rev-parse --show-toplevel
    Hook->>Hook: sed (strip CRLF + comment lines)
    Hook->>Docker: docker compose run --rm -T --no-deps node sh -c '...'
    Docker->>Docker: check node_modules/.bin/commitlint exists AND lockfile not newer
    alt node_modules missing or stale
        Docker->>Docker: npm ci (lockfile-pinned install)
    end
    Docker->>CL: "exec node_modules/.bin/commitlint (stdin = cleaned message)"
    CL-->>Git: exit 0 (pass) or exit 1 (fail)
    Git-->>Dev: commit accepted or rejected

    Note over Dev,CL: CI path (pull_request event)
    participant GHA as GitHub Actions
    participant NPM as npm ci
    participant CL2 as commitlint

    GHA->>GHA: checkout (fetch-depth: 0)
    GHA->>NPM: npm ci --no-audit --no-fund
    NPM-->>GHA: packages installed (lockfile-pinned)
    GHA->>CL2: npx --no-install commitlint --from base.sha --to head.sha --verbose
    CL2-->>GHA: exit 0 (pass) or exit 1 (fail)

Loading

_{Reviews (3): Last reviewed commit: "fix(commitlint): run the node service be..." | Re-trigger Greptile}

[math3usmartins]

Too many files changed for review. (123 files found, 100 file limit)

Bypass the limit by tagging @greptile-apps to review.

@greptile-apps