fdb0c78827
- Move PRE_COMMIT_HOOKS.md to development/ (development-focused) - Move APP_NAME_CONFIGURATION.md to setup/ (configuration-focused) - Move ENVIRONMENT_VARIABLES.md to setup/ (configuration-focused) - Improves organization by grouping related documentation together - Makes it easier to find relevant docs based on purpose
213 lines
4.8 KiB
Markdown
213 lines
4.8 KiB
Markdown
# 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
|