# Enforce quality gates at commit time with Husky and lint-staged

- Status: accepted
- Date: 2026-04-26

## Context and Problem Statement

Without automated enforcement, code quality rules (linting, formatting, tests) are discovered late — in CI, or not at all. Should quality checks be enforced at commit time?

## Decision Drivers

- Issues should be caught before they enter the repository, not after.
- Formatting should be applied automatically so developers don't need to run it manually.
- The correct Node version must be active during hook execution regardless of the shell environment.

## Considered Options

- Husky + lint-staged pre-commit hook
- CI-only enforcement (no local hooks)
- No automated enforcement

## Decision Outcome

Chosen option: "Husky + lint-staged pre-commit hook", because it prevents lint errors and failing tests from entering the repository, and auto-fixes formatting on commit without developer intervention.

The hook runs in order:

1. Full test suite (`npm test -- --watch=false`) — blocks commit on any failing spec.
2. `lint-staged` on staged files: `prettier --write` on `*.{ts,html,scss,json,md}`, then `eslint --max-warnings=0` on `*.ts` and `*.html`.

nvm is initialised inside the hook script to ensure the correct Node version (pinned in `.nvmrc`) is active regardless of the shell environment that triggered the commit.

### Positive Consequences

- No lint errors or failing tests can enter the repository via a normal commit.
- Prettier auto-fixes formatting on commit — developers don't need to run it manually.

### Negative Consequences

- Commits are slower (~10–20 s for the full test suite). Acceptable trade-off for a solo project.
- Requires nvm to be installed on the developer's machine. The hook sources `$HOME/.nvm/nvm.sh` directly.

## Pros and Cons of the Options

### Husky + lint-staged

- Good, because issues are caught before they enter the repository.
- Good, because formatting is applied automatically.
- Bad, because adds latency to every commit.
- Bad, because requires nvm on the developer's machine.

### CI-only enforcement

- Good, because no local overhead.
- Bad, because broken commits are discovered only after push.

### No automated enforcement

- Good, because zero overhead.
- Bad, because quality degrades without consistent manual discipline.
