# 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)

```bash
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:

```bash
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

```bash
# See detailed type errors
bun run type-check

# Fix common issues
bun run lint:fix
```

#### Formatting Issues

```bash
# 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

```bash
# Reinstall hooks
bun run prepare

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

### Bypassing Hooks (Emergency Only)

```bash
# 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:

```bash
# 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