Quality Checks¶

This guide covers the quality assurance tools and workflows to ensure code quality before committing changes.

Overview¶

The project uses a comprehensive suite of automated tools to maintain code quality:

• Formatting: Ruff formatter
• Linting: Ruff linter
• Type Checking: ty static type checker
• Testing: Pytest with coverage

Running All Checks¶

Run all quality checks with a single command:

just check

This command runs all checks in sequence:

1. Format → Auto-fixes code style
2. Lint → Checks for code issues
3. Typecheck → Verifies type annotations
4. Test → Runs test suite with coverage

If all checks pass, you'll see:

All checks passed!

Individual Checks¶

Format Code¶

just format

Automatically formats all Python files using Ruff.

What it fixes:

• Line length (max 80 characters)
• Import ordering
• Trailing whitespace
• Quote normalization

Lint Code¶

just lint

Checks for code quality issues without modifying files.

What it checks:

• Unused imports
• Undefined variables
• Style violations
• Complexity issues

Type Check¶

just typecheck

Validates all type annotations using ty.

Requirements:

• 100% type hint coverage
• No type errors
• Proper return types

Run Tests¶

just test

Runs the full test suite with coverage reporting.

Requirements:

• All tests pass
• Coverage ≥ 95%

Pre-commit Hooks¶

Install pre-commit hooks to run checks automatically before every commit:

just pi  # Install hooks

After installation, hooks run automatically:

git commit -m "feat: add new feature"
# → Runs format, lint, typecheck automatically

To run hooks manually on all files:

just pr  # Run pre-commit on all files

CI Integration¶

All quality checks run automatically on every push via GitHub Actions:

# .github/workflows/ci.yml
- name: Run all quality checks
  run: just check

- name: Verify coverage threshold
  run: coverage report --fail-under=95

Pull requests cannot be merged until all checks pass ✅

Quality Standards¶

The project maintains strict quality standards:

Quick Reference¶

Troubleshooting¶

Format Conflicts¶

If Ruff format changes conflict with manual edits:

# Reformat everything
just format

Type Errors¶

If type checking fails:

1. Check return types include | None where needed
2. Add type parameters to generics: list[User]
3. Use from __future__ import annotations for forward refs

Coverage Below Threshold¶

If coverage drops below 95%:

# Generate HTML coverage report
pytest --cov=app --cov-report=html
open htmlcov/index.html

Find untested lines and add tests.

See Also¶

• Testing Guide — Writing and running tests
• Troubleshooting — Common quality check issues
• Contributing Guide — Development workflow