Automatic Linting Setup

This project uses pre-commit hooks to automatically run linters on every commit, ensuring code quality and consistency.

Quick Start

If you're setting up the project for the first time:

# Complete development setup (includes pre-commit)
make dev-setup

Or if you just want to set up linting:

# Just set up pre-commit hooks
make setup-pre-commit

What Gets Linted

The following checks run automatically before every commit:

Python Code

• black - Code formatting
• ruff - Fast Python linter (replaces flake8, isort, and more)
• mypy - Static type checking
• bandit - Security vulnerability scanning

Infrastructure Code

• terraform fmt - Terraform formatting
• terraform validate - Terraform syntax validation
• hadolint - Dockerfile linting
• shellcheck - Shell script analysis

Configuration Files

• YAML syntax checking - Validates YAML files
• JSON syntax checking - Validates JSON files
• TOML syntax checking - Validates TOML files

Security & Best Practices

• Detect private keys - Prevents committing secrets
• Large file check - Warns about files >1MB
• Merge conflict markers - Detects unresolved conflicts
• Trailing whitespace - Removes trailing spaces
• End of file fixer - Ensures files end with newline

Manual Linting Commands

Run all linters manually:

make lint

Auto-fix issues where possible:

make lint-fix

Run pre-commit on all files:

pre-commit run --all-files

Run specific linter:

# Python only
make app-lint

# Terraform only
make tf-lint

# Helm charts only
make helm-lint

Bypassing Linting (Not Recommended)

In rare cases where you need to commit without linting:

git commit --no-verify -m "Emergency fix"

Warning: This should only be used in emergencies. Always fix linting issues afterward.

Configuring Linters

Python Linting Rules

Python linting configuration is in:
- pyproject.toml - ruff, black, and mypy settings
- config/.pre-commit-config.yaml - Pre-commit hook configuration

Terraform Linting

Terraform formatting follows standard conventions. No custom configuration needed.

Adding New Linters

To add a new linter, edit config/.pre-commit-config.yaml:

- repo: https://github.com/example/new-linter
  rev: v1.0.0
  hooks:
    - id: new-linter

Then update the hooks:

pre-commit autoupdate
make setup-pre-commit

Troubleshooting

Pre-commit not running

Ensure hooks are installed:

make setup-pre-commit

Linting errors on CI but not locally

Update your pre-commit hooks:

pre-commit autoupdate
pre-commit run --all-files

Type checking errors

Install type stubs:

pip install types-requests types-redis types-pyyaml

IDE Integration

VS Code

Add to .vscode/settings.json:

{
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  }
}

PyCharm

1. Go to Settings → Tools → File Watchers
2. Add watchers for black and ruff
3. Enable "Reformat on Save"

Best Practices

1. Fix linting issues immediately - Don't let them accumulate
2. Run lint-fix first - Many issues can be auto-fixed
3. Read linter messages - They often explain the issue and solution
4. Don't disable linters - Fix the underlying issue instead
5. Keep linters updated - Run pre-commit autoupdate periodically