/code-quality

name: code-quality
description: Agents should invoke this skill for code reviews, linting/formatting setup, maintainability checks, complexity concerns, warning cleanup, coding standards, or quality gates in Rust, TypeScript, Python, shell, and mixed repos.
license: MIT (modified; see UPSTREAMS.json)

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`):

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

**Standard commands:**

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:**

{
  "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`:**

[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 | | Pyt