Pre-Commit Quality Gate

Runs a comprehensive quality checklist (linting, type checking, formatting, tests) before every commit, ensuring only validated code enters the repository.

When to Use This Hook

Attach this hook when you need to:

• Enforce multiple quality checks as a single pre-commit gate across the team
• Catch linting errors, type violations, and test failures before they reach CI
• Standardize the quality bar for all commits regardless of developer setup

Consider alternatives when:

• Your team has individual pre-commit hooks for each check and prefers granular control
• Pre-commit checks take more than 30 seconds and slow down your commit workflow

Quick Start

Configuration

Copy
name: pre-commit-quality-gate
type: hook
trigger: PreToolUse
category: code-review

Example Trigger

Copy
# Hook triggers before a git commit command
git commit -m "fix: resolve race condition in auth flow"
# Quality gate runs all checks on staged files

Example Output

Pre-Commit Quality Gate
  Staged files: 5
  Step 1/4: Lint check .............. PASS (0 errors, 1 warning)
  Step 2/4: Type check .............. PASS (no type errors)
  Step 3/4: Format check ............ PASS (all files formatted)
  Step 4/4: Quick tests ............. PASS (23 tests, 1.8s)
Quality gate: ALL PASSED
Commit proceeding.

Core Concepts

Quality Checks Overview

Aspect	Details
Lint Check	ESLint, Pylint, or language-appropriate linter on staged files
Type Check	TypeScript tsc --noEmit or mypy for Python
Format Check	Prettier/Black --check mode for formatting compliance
Quick Tests	Fast unit tests related to changed files
Custom Checks	Project-specific validators (e.g., i18n key completeness)

Quality Gate Workflow

Commit Initiated
       |
  Get Staged Files
       |
  Run Checks Sequentially
       |
  Lint ──→ Types ──→ Format ──→ Tests
   |         |         |         |
   └─────────┼─────────┴─────────┘
             |
        All Passed?
         /       \
       Yes        No
        |          |
     ALLOW      BLOCK +
     Commit     First Failure
                Report

Configuration

Parameter	Type	Default	Description
checks	string[]	["lint","typecheck","format","test"]	Ordered list of quality checks to run
fail_fast	boolean	true	Stop at first failing check vs run all
lint_command	string	"npx eslint"	Linting command for staged files
type_command	string	"npx tsc --noEmit"	Type checking command
test_command	string	"npm run test:quick"	Quick test command

Best Practices

1. Use Fail-Fast Mode - Stop at the first failing check to give developers immediate feedback. Running all checks when lint already fails wastes time and produces noise.

2. Check Only Staged Files - Run lint and format checks only on staged files, not the entire codebase. This keeps checks fast and focuses feedback on the code being committed.

3. Order Checks by Speed - Run the fastest checks first (lint, then types, then format, then tests). Developers get quick feedback on simple issues before waiting for slower checks.

4. Allow Override for WIP Commits - Provide a --no-verify escape hatch documentation for genuine work-in-progress commits to non-shared branches. Do not make the gate so rigid that it blocks productive workflows.

5. Keep Total Time Under 15 Seconds - If the quality gate takes longer than 15 seconds, developers will avoid committing frequently. Optimize each check or parallelize independent checks.

Common Issues

1. Type Check Scanning Full Project - tsc --noEmit checks the entire project, not just staged files. This is by design since types are global, but it can be slow. Use incremental compilation for speed.

2. Conflicting Lint and Format Rules - ESLint formatting rules may conflict with Prettier. Install eslint-config-prettier to disable overlapping rules.

3. Test Failures from Unrelated Changes - Tests failing due to changes in other branches or shared state confuse developers. Ensure test isolation and use --findRelatedTests when possible.