# Code Quality Tools
This project uses several tools to ensure code quality and consistency.
## Tools
### 1. **mypy** - Static Type Checking
Type checking with strict rules to catch type errors before runtime.
**Configuration**: `pyproject.toml` → `[tool.mypy]`
**Run manually**:
```bash
make type-check
# or
uv run mypy src/mcp_caldav --ignore-missing-imports
```
**Key settings**:
- Strict type checking enabled
- Disallows untyped function definitions
- Checks untyped function calls
- Tests excluded from strict checking
### 2. **ruff** - Linting and Formatting
Fast Python linter and formatter that replaces multiple tools (flake8, isort, black, etc.).
**Configuration**: `pyproject.toml` → `[tool.ruff]`
**Run manually**:
```bash
# Check for issues
make lint
# Auto-fix issues (lint with --fix)
make lint # ruff auto-fixes when possible
# Format code
make format
```
**Enabled rules**:
- `E`, `W` - pycodestyle errors and warnings
- `F` - pyflakes
- `I` - isort (import sorting)
- `B` - flake8-bugbear
- `C4` - flake8-comprehensions
- `UP` - pyupgrade
- `SIM` - flake8-simplify
- `TCH` - flake8-type-checking
- `TID` - flake8-tidy-imports
- `Q` - flake8-quotes
- `RUF` - ruff-specific rules
### 3. **pre-commit** - Git Hooks
Automatically runs quality checks before each commit.
**Configuration**: `.pre-commit-config.yaml`
**Setup**:
```bash
uv run pre-commit install
```
**Run manually**:
```bash
# Run on all files
make pre-commit-run
# or
uv run pre-commit run --all-files
# Run on staged files only
uv run pre-commit run
```
**Hooks configured**:
- Trailing whitespace removal
- End of file fixer
- YAML/JSON/TOML validation
- Large file detection
- Merge conflict detection
- Debug statement detection
- Ruff linting and formatting
- mypy type checking
## Workflow
### Before Committing
1. **Automatic checks** (via pre-commit hook):
- Runs automatically when you `git commit`
- Fixes auto-fixable issues
- Blocks commit if errors remain
2. **Manual checks** (optional):
```bash
# Run all checks
make check
# Or individually
make lint
make format
make type-check
```
### CI/CD Integration
Add to your CI pipeline:
```yaml
- name: Code Quality Checks
run: |
uv sync --group dev
uv run ruff check src/
uv run ruff format --check src/
uv run mypy src/mcp_caldav --ignore-missing-imports
```
## Ignoring Rules
### Ruff
Add to `pyproject.toml`:
```toml
[tool.ruff.lint.per-file-ignores]
"tests/*" = ["ARG", "S101", "PLR2004"]
```
### mypy
Add inline comments:
```python
some_code() # type: ignore[error-code]
```
Or in `pyproject.toml`:
```toml
[[tool.mypy.overrides]]
module = "module.name"
ignore_missing_imports = true
```
## Common Issues and Fixes
### Import Sorting (I001)
```bash
uv run ruff check --fix src/ # Auto-fixes
```
### Type Annotations (UP006, UP035)
- Use `list` instead of `List`
- Use `dict` instead of `Dict`
- Use `X | Y` instead of `Union[X, Y]`
- Use `X | None` instead of `Optional[X]`
### Exception Handling (B904)
Always use `raise ... from err` or `raise ... from None`:
```python
except Exception as e:
raise RuntimeError("message") from e
```
### Unused Arguments (ARG001)
Prefix with `_` or add `# noqa: ARG001`:
```python
def func(_unused_arg: int) -> None: # or # noqa: ARG001
pass
```
## Configuration Files
- `pyproject.toml` - mypy and ruff configuration
- `.pre-commit-config.yaml` - pre-commit hooks configuration
- `.ruff.toml` - Alternative ruff config (if needed)
## Dependencies
All quality tools are in the `dev` dependency group:
```bash
uv sync --group dev
```
This installs:
- `mypy>=1.8.0`
- `ruff>=0.4.0`
- `pre-commit>=3.6.0`
- `types-click>=7.1.0` (type stubs for click)
