# Quality Checks & Pre-commit Hooks

**When to use:** Setting up your dev environment, understanding CI/local parity, or debugging pre-commit failures.

## Prerequisites

- Rust toolchain installed (`rustup`)
- `jscpd` for duplication checks: `npm install -g jscpd`

## Quick Start

```bash
# Run all quality checks (same as CI)
make quality

# Auto-fix formatting
make fmt

# See clippy errors
make lint
```

## Pre-commit Hook

The pre-commit hook at `.git/hooks/pre-commit` runs automatically on every commit. It:

1. Checks if any Rust files are staged
2. Runs `make quality` (format check, clippy, duplication, tests)
3. Blocks commit if any check fails

### Installing the Hook

The hook should already exist. If not:

```bash
# Copy the sample and make executable
cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

### Bypassing (Emergency Only)

```bash
# Skip pre-commit hook (logged, use sparingly)
git commit --no-verify -m "emergency fix"
```

## What Gets Checked

| Check | Command | What it catches |
|-------|---------|-----------------|
| Format | `cargo fmt --check` | Inconsistent formatting |
| Lint | `cargo clippy -- -D warnings` | Code smells, potential bugs |
| Duplication | `jscpd` | Copy-pasted code blocks |
| Tests | `cargo test` | Broken functionality |

## Enforced Lints

These are set to `deny` in `Cargo.toml` (CI will fail):

| Lint | Why |
|------|-----|
| `clippy::unwrap_used` | Panics are forbidden in production code |
| `clippy::expect_used` | Panics are forbidden in production code |
| `clippy::panic` | Explicit panics are forbidden in production code |

**Tests are exempt** via `clippy.toml`:
- `allow-unwrap-in-tests = true`
- `allow-expect-in-tests = true`
- `allow-panic-in-tests = true`

To add a new enforced lint, update `[workspace.lints.clippy]` in root `Cargo.toml`.

## Troubleshooting

### "Format check failed"

```bash
make fmt  # Auto-fix
git add -u  # Re-stage fixed files
```

### "Clippy warnings treated as errors"

Fix the warnings. Common ones:

```rust
// Bad: unused variable
let x = 5;

// Good: prefix with underscore
let _x = 5;
```

### "Duplication detected"

Refactor the duplicated code into a shared function or module.

## CI/Local Parity

The pre-commit hook runs `make quality`, which is the **exact same** command CI runs. If it passes locally, it passes in CI.

## Related

- [Testing Guide](./testing.md) - Running tests
- [Rust Guidelines](../backend/rust-guidelines.md) - Code standards