Initial commit: Complete NodeJS-native setup
- Migrated from Python pre-commit to NodeJS-native solution - Reorganized documentation structure - Set up Husky + lint-staged for efficient pre-commit hooks - Fixed Dockerfile healthcheck issue - Added comprehensive documentation index
This commit is contained in:
William Valentin
246
docs/development/CODE_QUALITY.md
Normal file
246
docs/development/CODE_QUALITY.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# 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
|
||||
npx eslint --print-config index.tsx
|
||||
```
|
||||
Reference in New Issue
Block a user