TL-M0-07 · Commit messages: commitlint and Lefthook

Why: Lefthook runs Biome on staged files and checks the commit message, and nothing slower runs on commit (D6). Lefthook's own install script is allowed, so the hooks reinstall on every pnpm install, including on the second developer's machine.

ID TL-M0-07 · Level L0 · Run order row 7

Goal

A commit runs Biome on the staged files and refuses a message that isn't a Conventional Commit.

Before

TL-M0-06 is Done.

Run

1 · The hook config and the commit message rules

cat > lefthook.yml <<'EOF'
# Kept light on purpose (D6): only Biome and the commit message check run on commit.
# Typecheck and tests run on push and in CI.
pre-commit:
  commands:
    biome:
      glob: "*.{js,jsx,ts,tsx,mjs,cjs,json,jsonc,css}"
      run: pnpm biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}
      stage_fixed: true

commit-msg:
  commands:
    commitlint:
      run: pnpm commitlint --edit {1}
EOF
cat > commitlint.config.mjs <<'EOF'
// Conventional Commits. Scopes are package names (D6); repo-wide changes take no scope.
export default {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "scope-enum": [2, "always", ["web", "docs", "db-types", "supabase", "tools"]],
  },
};
EOF

2 · Add the tools. --allow-build=lefthook approves Lefthook's install script; without it pnpm 12 stops with ERR_PNPM_IGNORED_BUILDS

pnpm add -Dw -E @commitlint/cli@21.2.3 @commitlint/config-conventional@21.2.3 lefthook@2.1.16 --allow-build=lefthook

3 · Try a bad commit message, then a good one

git add -A
git commit -m "added hooks"
git commit -m "build: add commitlint and Lefthook"

Expect

• Block 2: the three packages added, then “lefthook postinstall: sync hooks: ✔️ (commit-msg, pre-commit)”.
• Block 3: the first commit is refused with “✖ subject may not be empty [subject-empty]” and “✖ type may not be empty [type-empty]”. The second shows ✔️ biome and ✔️ commitlint, then the commit line.

Check

cat pnpm-workspace.yaml
ls .git/hooks | grep -v sample
git log --oneline | head -1

allowBuilds lists lefthook: true. The hooks are commit-msg and pre-commit. The last commit is “build: add commitlint and Lefthook”.

If it fails

• The bad message is accepted: paste the output of ls .git/hooks and cat lefthook.yml.
• ERR_PNPM_IGNORED_BUILDS naming lefthook: the --allow-build flag was dropped; run block 2 again with it.

Undo

pnpm lefthook uninstall
git reset --hard HEAD~1
pnpm install

Runs

Done 2026-10-05 (zuki)