8fa2d3fb60
checks - Replace npm commands with bun/bunx in scripts, docs, and CI - Add enhanced pre-commit checks with parallel execution - Document pre-commit hook behavior in PRE_COMMIT_HOOKS.md - Update .gitignore/.dockerignore for bun-debug.log - Refine ESLint config for bun and Prettier integration - Add scripts/type-check-staged.sh for fast staged type checks - Improve developer workflow and code quality automation
247 lines
6.4 KiB
Markdown
247 lines
6.4 KiB
Markdown
# Code Quality and Formatting Setup
|
|
|
|
This project includes comprehensive code quality tools and pre-commit hooks to maintain consistent code standards.
|
|
|
|
## Tools Configured
|
|
|
|
### Pre-commit Hooks
|
|
|
|
- **File formatting**: Trailing whitespace, end-of-file fixes, line ending normalization
|
|
- **Security**: Private key detection, secrets scanning with detect-secrets
|
|
- **Linting**: ESLint for TypeScript/JavaScript, Hadolint for Docker, ShellCheck for scripts
|
|
- **Type checking**: TypeScript compilation checks
|
|
- **Formatting**: Prettier for code formatting, Markdownlint for documentation
|
|
|
|
### Code Formatters
|
|
|
|
- **Prettier**: Handles JavaScript, TypeScript, JSON, YAML, Markdown, CSS, SCSS, HTML formatting
|
|
- **ESLint**: TypeScript/JavaScript linting with comprehensive rules and React hooks support
|
|
- **EditorConfig**: Consistent coding styles across editors
|
|
|
|
### Security Tools
|
|
|
|
- **detect-secrets**: Prevents secrets from being committed to the repository
|
|
- **Private key detection**: Automatically detects and blocks private keys
|
|
|
|
## Setup
|
|
|
|
Run the setup script to install all tools and configure pre-commit hooks:
|
|
|
|
```bash
|
|
./scripts/setup-pre-commit.sh
|
|
```
|
|
|
|
Alternatively, install manually:
|
|
|
|
```bash
|
|
# Install dependencies
|
|
bun install
|
|
|
|
# Install pre-commit in Python virtual environment
|
|
python -m venv .venv
|
|
source .venv/bin/activate # or .venv/Scripts/activate on Windows
|
|
pip install pre-commit detect-secrets
|
|
|
|
# Install pre-commit hooks
|
|
pre-commit install
|
|
|
|
# Create secrets baseline (if it doesn't exist)
|
|
detect-secrets scan --baseline .secrets.baseline
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Automatic (Recommended)
|
|
|
|
Pre-commit hooks will automatically run on every commit, ensuring:
|
|
|
|
- Code is properly formatted
|
|
- Linting rules are followed
|
|
- Type checking passes
|
|
- No secrets are committed
|
|
|
|
### Manual Commands
|
|
|
|
```bash
|
|
# Format all files
|
|
bun run format
|
|
|
|
# Check formatting without fixing
|
|
bun run format:check
|
|
|
|
# Lint TypeScript/JavaScript files
|
|
bun run lint
|
|
|
|
# Lint with auto-fix
|
|
bun run lint:fix
|
|
|
|
# Type checking
|
|
bun run type-check
|
|
|
|
# Run pre-commit hook
|
|
bun run pre-commit
|
|
|
|
# Run all pre-commit hooks manually (using virtual environment)
|
|
/home/will/Code/meds/.venv/bin/pre-commit run --all-files
|
|
|
|
# Run specific hook
|
|
/home/will/Code/meds/.venv/bin/pre-commit run prettier --all-files
|
|
|
|
# Update pre-commit hook versions
|
|
/home/will/Code/meds/.venv/bin/pre-commit autoupdate
|
|
```
|
|
|
|
## Configuration Files
|
|
|
|
- `.pre-commit-config.yaml` - Pre-commit hooks configuration with comprehensive security and quality checks
|
|
- `.prettierrc` - Prettier formatting rules with TypeScript/React optimizations
|
|
- `.prettierignore` - Files to ignore for Prettier formatting
|
|
- `.editorconfig` - Editor configuration for consistent coding styles across IDEs
|
|
- `eslint.config.cjs` - ESLint linting rules with TypeScript and React hooks support
|
|
- `.markdownlint.json` - Markdown linting configuration for documentation quality
|
|
- `.secrets.baseline` - Baseline for detect-secrets security scanning
|
|
- `scripts/setup-pre-commit.sh` - Automated setup script for all tools
|
|
- `docs/CODE_QUALITY.md` - This documentation file
|
|
|
|
## Pre-commit Hook Details
|
|
|
|
The following hooks run automatically on every commit:
|
|
|
|
### File Quality Hooks
|
|
|
|
- `trailing-whitespace` - Removes trailing whitespace
|
|
- `end-of-file-fixer` - Ensures files end with newline
|
|
- `check-yaml` - Validates YAML syntax
|
|
- `check-json` - Validates JSON syntax
|
|
- `check-toml` - Validates TOML syntax
|
|
- `check-xml` - Validates XML syntax
|
|
- `check-merge-conflict` - Prevents merge conflict markers
|
|
- `check-added-large-files` - Prevents large files from being committed
|
|
- `check-case-conflict` - Prevents case conflicts on case-insensitive filesystems
|
|
- `check-symlinks` - Validates symlinks
|
|
- `mixed-line-ending` - Ensures consistent line endings (LF)
|
|
|
|
### Security Hooks
|
|
|
|
- `detect-private-key` - Prevents private keys from being committed
|
|
- `detect-secrets` - Scans for secrets using baseline comparison
|
|
|
|
### Code Quality Hooks
|
|
|
|
- `prettier` - Formats JavaScript, TypeScript, JSON, YAML, Markdown, CSS, SCSS, HTML
|
|
- `eslint` - Lints TypeScript/JavaScript with auto-fix
|
|
- `tsc` - TypeScript type checking
|
|
|
|
### Infrastructure Hooks
|
|
|
|
- `hadolint-docker` - Lints Dockerfile files
|
|
- `shellcheck` - Lints shell scripts
|
|
- `markdownlint` - Lints and formats Markdown files
|
|
|
|
## IDE Integration
|
|
|
|
### VS Code (Recommended)
|
|
|
|
Install these extensions for optimal integration:
|
|
|
|
- **Prettier - Code formatter** (`esbenp.prettier-vscode`)
|
|
- **ESLint** (`dbaeumer.vscode-eslint`)
|
|
- **EditorConfig for VS Code** (`editorconfig.editorconfig`)
|
|
|
|
### Settings for VS Code
|
|
|
|
Add these settings to your VS Code `settings.json`:
|
|
|
|
```json
|
|
{
|
|
"editor.formatOnSave": true,
|
|
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
|
"editor.codeActionsOnSave": {
|
|
"source.fixAll.eslint": true
|
|
},
|
|
"eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"]
|
|
}
|
|
```
|
|
|
|
### Other IDEs
|
|
|
|
Most modern IDEs support EditorConfig, Prettier, and ESLint through plugins:
|
|
|
|
- **WebStorm/IntelliJ**: Built-in support for most tools
|
|
- **Vim/Neovim**: Use coc.nvim or native LSP with appropriate plugins
|
|
- **Sublime Text**: Install Package Control packages for each tool
|
|
|
|
## Customization
|
|
|
|
### Prettier
|
|
|
|
Edit `.prettierrc` to modify formatting rules.
|
|
|
|
### ESLint
|
|
|
|
Edit `eslint.config.cjs` to add or modify linting rules.
|
|
|
|
### Pre-commit
|
|
|
|
Edit `.pre-commit-config.yaml` to add, remove, or modify hooks.
|
|
|
|
## Troubleshooting
|
|
|
|
### Pre-commit hooks failing
|
|
|
|
```bash
|
|
# Skip hooks temporarily (not recommended)
|
|
git commit --no-verify -m "commit message"
|
|
|
|
# Fix issues and try again
|
|
bun run lint:fix
|
|
bun run format
|
|
git add .
|
|
git commit -m "commit message"
|
|
```
|
|
|
|
### Update hook versions
|
|
|
|
```bash
|
|
/home/will/Code/meds/.venv/bin/pre-commit autoupdate
|
|
```
|
|
|
|
### Clear pre-commit cache
|
|
|
|
```bash
|
|
/home/will/Code/meds/.venv/bin/pre-commit clean
|
|
```
|
|
|
|
### Secrets detection issues
|
|
|
|
```bash
|
|
# Update secrets baseline
|
|
/home/will/Code/meds/.venv/bin/detect-secrets scan --update .secrets.baseline
|
|
|
|
# Audit detected secrets
|
|
/home/will/Code/meds/.venv/bin/detect-secrets audit .secrets.baseline
|
|
```
|
|
|
|
### Python virtual environment issues
|
|
|
|
```bash
|
|
# Recreate virtual environment
|
|
rm -rf .venv
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install pre-commit detect-secrets
|
|
/home/will/Code/meds/.venv/bin/pre-commit install
|
|
```
|
|
|
|
### ESLint configuration issues
|
|
|
|
If you encounter TypeScript project configuration errors:
|
|
|
|
```bash
|
|
# Ensure tsconfig.json is properly configured
|
|
bun run type-check
|
|
|
|
# Check ESLint configuration
|
|
bunx eslint --print-config index.tsx
|
|
```
|