docs: reorganize files into logical folder structure

- 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
2025-09-08 21:37:25 -07:00
parent 8f70dca7b7
commit fdb0c78827
3 changed files with 3 additions and 3 deletions
--- a/docs/development/PRE_COMMIT_HOOKS.md
+++ b/docs/development/PRE_COMMIT_HOOKS.md
@@ -0,0 +1,212 @@
+# 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