code-quality

# Code Quality

Structured code review and quality enforcement across common tech stacks. Checklists, linting strategies, and metrics to keep codebases healthy.

## Quick Start

### Run a Code Quality Check

1. **Run static analysis:** Linters, type checkers, formatters
2. **Review against checklist:** Language-specific items below
3. **Check complexity metrics:** Cyclomatic < 25, data flow < 25
4. **Report findings:** Structured output with severity and recommendations

---

## Linting Configurations

### Rust — Clippy Config

Standard clippy configuration (in `Cargo.toml` or `.clippy.toml`):

```toml
[lints.clippy]
cognitive_complexity = "warn"
pedantic = { level = "deny", priority = -1 }
nursery = { level = "deny", priority = -1 }
unwrap_used = "deny"
```

**Standard commands:**

```bash
cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo check
cargo test -- --test-threads=1
```

**Key rules to enforce:**
- No `.unwrap()` in non-test code (use `?` or `.expect("reason")`)
- All public items have rustdoc (`#[warn(missing_docs)]`)
- `#[must_use]` on functions that return values that should be checked
- When using `#[allow(...)]`, always add a comment explaining why
- If no good explanation exists for `#[allow(...)]`, fix the issue instead

### TypeScript — ESLint + Strict Mode

**Recommended `tsconfig.json` strictness:**

```json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true
  }
}
```

**Key rules to enforce:**
- No `any` — use `unknown` and type guards instead
- No `// @ts-ignore` — fix the type issue or use `// @ts-expect-error` with explanation
- Prefer `const` over `let`, never use `var`
- Use discriminated unions for state modeling
- Explicit return types on exported functions

### Python — Ruff + Mypy

**Recommended `pyproject.toml`:**

```toml
[tool.ruff]
target-version = "py312"
line-length = 88

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "ANN", "B", "A", "C4", "DTZ", "ISC", "PIE", "PT", "RET", "SIM", "TCH", "ARG", "PTH", "ERA"]

[tool.mypy]
strict = true
warn_return_any = true
warn_unreachable = true
```

**Key rules to enforce:**
- Type hints on all public functions and methods
- Docstrings on all public classes, functions, and methods
- Use `pathlib.Path` over `os.path`
- Use `uv` as package manager
- No bare `except:` — always catch specific exceptions

---

## Code Review Checklists

### Universal Checklist (All Languages)

**Correctness:**
- [ ] Does the code do what it claims to do?
- [ ] Are edge cases handled (empty collections, null/None, zero, negative)?
- [ ] Are error paths handled gracefully?
- [ ] Are there any off-by-one errors?

**Clarity:**
- [ ] Can you understand the code without the PR description?
- [ ] Are variable/function names descriptive and consistent?
- [ ] Are complex sections commented with "why" (not "what")?
- [ ] Is the code self-documenting where possible?

**Architecture:**
- [ ] Does this change respect existing module boundaries?
- [ ] Is the change at the right abstraction level?
- [ ] Are dependencies reasonable (not pulling in a huge lib for one function)?

**Testing:**
- [ ] Are new functions/methods covered by tests?
- [ ] Do tests cover edge cases and error paths?
- [ ] Are tests readable and maintainable?

**Security (flag for a security follow-up if concerns found):**
- [ ] No hardcoded secrets or credentials
- [ ] User input is validated before use
- [ ] No SQL injection, XSS, or path traversal vectors

### Rust-Specific Checklist

- [ ] `cargo fmt` applied
- [ ] `cargo clippy` clean (pedantic + nursery)
- [ ] No `.unwrap()` outside tests
- [ ] Error handling uses `?` with proper error types
- [ ] Public items have rustdoc comments
- [ ] `#[allow(...)]` includes explanatory comment
- [ ] New functions have unit tests
- [ ] Cyclomatic complexity < 25 per function
- [ ] Data flow complexity < 25 per function

### TypeScript/React-Specific Checklist

- [ ] No `any` types
- [ ] Strict mode compliance
- [ ] Components have clear prop types
- [ ] Hooks follow rules of hooks
- [ ] No unnecessary re-renders (check memo/callback usage)
- [ ] Bundle impact considered for new dependencies

### Django/Python-Specific Checklist

- [ ] Type hints present on public interfaces
- [ ] Ruff + mypy clean
- [ ] No N+1 queries (use `select_related`/`prefetch_related`)
- [ ] Migrations are reviewed and reversible
- [ ] No business logic in views (use service layer)

---

## Complexity Metrics

### Cyclomatic Complexity

Measures the number of independent paths through code. Recommended threshold: **< 25**.

| Complexity | Risk Level | Action |
|---|---|---|
| 1-10 | Low | Simple, well-structured code |
| 11-20 | Moderate | Consider simplification if growing |
| 21-24 | High | Refactoring recommended |
| 25+ | Violation | Must refactor before merge |

**How to reduce:**
- Extract helper functions for each branch
- Use early returns / guard clauses
- Replace complex conditionals with lookup tables or pattern matching
- Use strategy pattern for variant-dependent behavior

### Data Flow Complexity

Measures how many variables interact within a function. Recommended threshold: **< 25**.

**How to reduce:**
- Extract pure functions that take fewer parameters
- Group related parameters into structs/objects
- Split functions that transform data in multiple stages

### Measurement Tools

| Language | Tool | Command |
|---|---|---|
| Rust | `cargo clippy` (cognitive_complexity) | Built into clippy config |
| TypeScript | `eslint-plugin-sonarjs` | Configure `complexity` rule |
| Python | `radon` | `radon cc <file> -s -a` |
| Python | `ruff` | Rule `C901` (mccabe complexity) |

---

## Review Output Format

When delivering a code review:

```markdown
## Code Review: [PR/File/Module]

**Date:** YYYY-MM-DD

### Summary
[1-2 sentences: overall quality assessment]

### Findings

| # | Severi