Implement pre-commit hooks with Husky to run lint and tests

[vlavrynovych]

Problem

Currently, linting and test failures are only caught in CircleCI/GitHub Actions after code is pushed. This leads to:

• Failed CI/CD builds that could have been prevented locally
• Wasted time waiting for CI feedback
• Additional commits to fix simple linting errors
• Broken master/release branches if checks are bypassed

Recent example: Issue #80 had ESLint errors that passed locally but failed in CircleCI due to unused imports and variables.

Solution

Implement Option 2: Husky with Full Test Suite - run comprehensive checks before every commit.

Pre-Commit Hook Configuration

.husky/pre-commit:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

echo "🔍 Running pre-commit checks..."

# Run linting
echo "📝 Running ESLint..."
npm run lint || exit 1

# Run tests with coverage
echo "🧪 Running tests with coverage..."
npm run test:coverage || exit 1

# Check coverage threshold
echo "📊 Verifying 100% coverage..."
npx nyc check-coverage --lines 100 --branches 100 --functions 100 --statements 100 || exit 1

echo "✅ All pre-commit checks passed!"

Installation Steps

# Install Husky
npm install --save-dev husky

# Initialize Husky
npx husky init

# Create pre-commit hook (content above)

package.json update:

{
  "scripts": {
    "prepare": "husky install"
  }
}

Benefits

✅ Catch errors immediately - Before they reach CI/CD
✅ Maintain 100% coverage - Enforced on every commit
✅ Consistent code quality - ESLint rules applied automatically
✅ Faster CI/CD - Fewer failed builds
✅ Team alignment - Everyone runs the same checks

Considerations

⚠️ Slower commits - May take 30-60 seconds per commit (acceptable for quality)
⚠️ Can be bypassed - Developers can use git commit --no-verify (document when this is acceptable)
⚠️ Local setup required - Team must run npm install after pulling

Acceptance Criteria

• Husky installed and configured
• Pre-commit hook runs ESLint
• Pre-commit hook runs full test suite
• Pre-commit hook verifies 100% coverage
• Documentation updated with bypass instructions (--no-verify for WIP)
• Team notified of new workflow
• Tested on all platforms (macOS, Linux, Windows)

Related

• Issue Add observability and metrics collection #80 - ESLint errors caught in CI that should have been caught locally
• CircleCI config: .circleci/config.yml
• ESLint config: package.json (eslintConfig)

Implementation Notes

• Consider adding commitlint in future for commit message standards
• Could add lint-staged later for faster staged-file-only checks
• May want to add TypeScript type checking (tsc --noEmit) to hook

[vlavrynovych]

✅ Pre-commit hooks successfully implemented and verified!

Implementation Summary

Installed and configured Husky with a comprehensive pre-commit hook that runs 5 quality checks:

1. TypeScript Type Check - npx tsc --noEmit validates types without emitting files
2. Build Check - npm run build ensures project compiles successfully
3. ESLint - Enforces code style and catches errors
4. Full Test Suite - Runs all unit and integration tests with coverage
5. Coverage Verification - Ensures 100% coverage maintained

Files Changed

Implementation:

• package.json - Added Husky dependency + prepare script
• package-lock.json - Updated dependencies
• .husky/pre-commit - Pre-commit hook script with all checks

Documentation:

• README.md - Removed Development section, fixed NPM-incompatible callouts
• docs/development/setup.md - Added comprehensive pre-commit hooks section
• docs/development/workflow.md - Updated workflow with hook information
• docs/development/contributing.md - Added note about automatic checks
• docs/development/index.md - Updated development standards

Testing

✅ Hook successfully tested and verified working
✅ All checks pass (type check, build, lint, tests, coverage)
✅ Execution time: ~60-90 seconds per commit

Notes

• Husky deprecation warning: The hook shows a deprecation warning about v10.0.0 format changes. This is expected with Husky v9.x and doesn't affect functionality. We can address this when Husky v10 is released.
• Bypassing hooks: Use git commit --no-verify for WIP commits on feature branches only (never on master/release branches)

Next Steps

Pre-commit hooks are now active for all contributors. The hooks will run automatically on every commit, ensuring code quality before changes reach the repository.