rxminder/docs/development/PRE_COMMIT_HOOKS.md

Pre-commit Hooks Documentation

This project uses enhanced pre-commit hooks to ensure code quality while maintaining fast commit speeds. The hooks run automatically before each commit and can be configured for different scenarios.

Overview

The pre-commit hooks perform the following checks on staged files only:

• ✅ Code Formatting (Prettier)
• ✅ Code Linting (ESLint with auto-fix)
• ✅ Type Checking (TypeScript)
• ✅ Markdown Linting (markdownlint-cli2)
• ✅ Secret Scanning (secretlint)

Quick Start

Normal Commits (Enhanced Checks)

git add .
git commit -m "Your commit message"

The enhanced pre-commit hooks will run automatically.

Fast Commits (Basic Checks Only)

For quick commits when you're in a hurry:

FAST_COMMIT=1 git commit -m "Quick fix"

This runs only Prettier formatting, skipping other checks.

What Gets Checked

JavaScript/TypeScript Files (_.js, _.jsx, _.ts, _.tsx)

• Prettier: Auto-formats code style
• ESLint: Lints and auto-fixes code issues
• TypeScript: Type checks (TypeScript files only)

Markdown Files (*.md)

• Prettier: Formats markdown
• markdownlint: Checks markdown style and fixes issues

Other Files (_.json, _.yaml, _.yml, _.css, _.scss, _.html)

• Prettier: Auto-formats files
• secretlint: Scans for potential secrets

Performance Optimizations

The hooks are designed to be fast:

1. Staged Files Only: Only checks files you're actually committing
2. Parallel Execution: Multiple checks run simultaneously
3. Smart Filtering: Skips checks if no relevant files are staged
4. Incremental TypeScript: Uses optimized TypeScript checking
5. Fast Mode: Available for urgent commits

Configuration Files

Prettier (.prettierrc)

• Semi-colons enabled
• Single quotes for JS/TS/JSX
• 80 character line width
• 2-space indentation
• Special rules for markdown and JSON

ESLint (eslint.config.cjs)

• TypeScript ESLint rules
• React Hooks rules
• Code quality enforcement
• Auto-fixing enabled

Secretlint (.secretlintrc.json)

• Scans for API keys, tokens, and secrets
• Prevents accidental secret commits

Markdownlint (.markdownlint.json)

• Consistent markdown formatting
• Documentation quality checks

Troubleshooting

Common Issues

Type Check Failures

# See detailed type errors
bun run type-check

# Fix common issues
bun run lint:fix

Formatting Issues

# Auto-format all files
bun run format

# Check what needs formatting
bun run format:check

Secret Detection

If secrets are detected:

1. Remove the secrets from your code
2. Add them to environment variables or config files
3. Update .secretlintrc.json if it's a false positive

Hook Not Running

# Reinstall hooks
bun run prepare

# Check if hooks are installed
ls -la .husky/

Bypassing Hooks (Emergency Only)

# Skip all pre-commit hooks (NOT RECOMMENDED)
git commit --no-verify -m "Emergency commit"

# Better: Use fast mode
FAST_COMMIT=1 git commit -m "Quick fix"

Manual Commands

Run individual checks manually:

# Format code
bun run format

# Lint and fix
bun run lint:fix

# Type check
bun run type-check

# Check markdown
bun run lint:markdown:fix

# Scan for secrets
bun run check:secrets

# Run all pre-commit checks manually
bun run pre-commit:enhanced

Scripts

Enhanced Pre-commit Script

• Location: scripts/pre-commit-checks.sh
• Purpose: Orchestrates all checks with parallel execution
• Features: Colored output, parallel processing, detailed error reporting

Fast TypeScript Checking

• Location: scripts/type-check-staged.sh
• Purpose: Optimized TypeScript checking for staged files only
• Features: Temporary tsconfig, fallback checking, fast execution

Environment Variables

• FAST_COMMIT=1: Enable fast commit mode (basic checks only)
• NO_VERIFY=1: Skip all hooks (use git commit --no-verify instead)

Tips for Fast Commits

1. Use Fast Mode: FAST_COMMIT=1 for urgent fixes
2. Stage Selectively: Only stage files you want to commit
3. Fix Issues Early: Run bun run lint:fix before committing
4. Keep Changes Small: Smaller commits = faster checks
5. Use IDE Integration: Configure your editor to run formatters on save

Contributing

When modifying the pre-commit hooks:

1. Test with various file types
2. Ensure parallel execution works
3. Maintain backward compatibility
4. Update this documentation
5. Consider performance impact

Related bun Scripts

• bun run pre-commit: Basic lint-staged checks
• bun run pre-commit:enhanced: Full enhanced checks
• bun run lint: ESLint check
• bun run lint:fix: ESLint auto-fix
• bun run format: Prettier format all
• bun run format:check: Check formatting
• bun run type-check: TypeScript check all files