ln-742-precommit-setup

Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-740-quality-setup

Sets up Git hooks for automated code quality enforcement before commits.

---

Purpose & Scope

Does:

• Installs hook management tools (Husky or pre-commit)
• Configures staged file linting (lint-staged or pre-commit hooks)
• Sets up commit message validation (commitlint)
• Verifies hooks trigger correctly

Does NOT:

• Configure linters themselves (ln-741 does this)
• Set up test infrastructure (ln-743 does this)
• Modify source code

---

Supported Stacks

Technology	Hook Manager	Staged Linting	Commit Validation
Node.js	Husky	lint-staged	commitlint
Python	pre-commit	pre-commit hooks	pre-commit hook
Mixed	Both (if needed)	Stack-specific	commitlint

---

Phase 1: Check Existing Hooks

Before installing, check for existing hook configurations.

Files to Check:

Tool	Indicators
Husky	.husky/ directory, husky in package.json
pre-commit	.pre-commit-config.yaml
lint-staged	lint-staged in package.json or .lintstagedrc*
commitlint	commitlint.config.*, .commitlintrc*

Decision Logic:

1. If hooks exist and working: SKIP (inform user)
2. If partial setup: ASK user to complete or replace
3. If no hooks: CREATE from templates

---

Phase 2: Install Hook Manager

Node.js Projects (Husky)

npm install -D husky
npx husky init

This creates:

• .husky/ directory
• .husky/pre-commit hook file
• Adds prepare script to package.json

Python Projects (pre-commit)

pip install pre-commit
# OR with uv:
uv add --dev pre-commit

pre-commit install

This creates:

• .git/hooks/pre-commit (managed by pre-commit)
• Requires .pre-commit-config.yaml for configuration

---

Phase 3: Configure Staged Linting

Node.js (lint-staged)

npm install -D lint-staged

Create configuration (.lintstagedrc.mjs or in package.json):

Key Rules:

• TypeScript files: ESLint + Prettier
• JSON/MD/CSS: Prettier only
• C# files: dotnet format (if mixed project)

CRITICAL FIX: For .NET files, use correct syntax: "*.cs": "dotnet format --include" is WRONG Use: "*.cs": "dotnet format whitespace --include" or run dotnet format separately

Python (pre-commit hooks)

Configuration in .pre-commit-config.yaml:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

---

Phase 4: Configure Commit Message Validation

Node.js (commitlint)

npm install -D @commitlint/cli @commitlint/config-conventional

Create commitlint.config.mjs with:

• Conventional Commits format
• Allowed types: feat, fix, docs, style, refactor, test, chore, ci
• Max header length: 100 characters

Update Husky hook

Add commit-msg hook:

echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

Python (pre-commit hook for commit message)

Add to .pre-commit-config.yaml:

  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.4.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]

---

Phase 5: Test Hooks

Verify hooks work correctly.

Test 1: Lint-staged triggers

# Create a file with lint issues
echo "const x=1" > test-file.ts
git add test-file.ts
git commit -m "test: verify hooks"
# Expected: lint-staged runs, either fixes or blocks

Test 2: Commit message validation

git commit --allow-empty -m "bad message"
# Expected: commitlint rejects

git commit --allow-empty -m "test: valid message format"
# Expected: commit succeeds

Cleanup:

rm test-file.ts
git reset HEAD~1  # If test commit was made

---

Critical Rules

RULE 1: Husky requires Git repository (git init first).

RULE 2: lint-staged MUST have linters configured first (run ln-741 before ln-742).

RULE 3: Document --no-verify escape hatch for emergency commits.

RULE 4: pre-commit hooks should auto-fix when possible (--fix flag).

---

Definition of Done

• Hook manager installed (Husky or pre-commit)
• Staged linting configured and working
• Commit message validation configured
• Test commit triggers hooks correctly
• User informed of:
  • How hooks work
  • How to skip hooks in emergency (git commit --no-verify)
  • Commit message format required

---

Reference Files

File	Purpose
husky_precommit_template.sh	Husky pre-commit hook
husky_commitmsg_template.sh	Husky commit-msg hook
lintstaged_template.mjs	lint-staged configuration
commitlint_template.mjs	commitlint configuration
precommit_config_template.yaml	Python pre-commit config
hooks_guide.md	Detailed hooks guide

---

Error Handling

Error	Cause	Resolution
Husky not running	Missing prepare script	Run npx husky init again
lint-staged fails	Missing linter	Run ln-741 first
pre-commit not found	Not in PATH	pip install pre-commit
Hooks not triggering	Git hooks disabled	Check .git/hooks/ permissions
Windows path issues	Shell script format	Use cross-platform syntax

---

Emergency Bypass

Document for users:

# Skip all hooks (use sparingly!)
git commit --no-verify -m "emergency: bypass hooks"

# Skip only pre-commit (keeps commit-msg)
HUSKY=0 git commit -m "fix: urgent hotfix"

---

Version: 2.0.0 Last Updated: 2026-01-10