rxminder/docs/development/CODE_QUALITY.md

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:

./scripts/setup-pre-commit.sh

Alternatively, install manually:

# 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

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

{
  "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

# 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

/home/will/Code/meds/.venv/bin/pre-commit autoupdate

Clear pre-commit cache

/home/will/Code/meds/.venv/bin/pre-commit clean

Secrets detection issues

# 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

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

# Ensure tsconfig.json is properly configured
bun run type-check

# Check ESLint configuration
bunx eslint --print-config index.tsx