georgekhananaev/code-quality

Code Quality

Production-grade code standards and review for TypeScript, Python, Go, and Rust.

When to Use

• Writing or reviewing code in TS/Python/Go/Rust
• Code review or pull request analysis
• Security or performance audit
• Setting up linting/CI for a project
• Python-specific style check (PEP 8)

Quick-Start Modes

| Intent | Sections to Use | |--------|----------------| | Write code | Core Rules + Language Standards + AI-Friendly Patterns | | Review PR | Review Process + references/checklist.md + Severity Levels | | Setup CI | Config Files + Scripts + Enforcement Strategy | | Python style | references/python.md (full PEP 8 deep-dive) |

Context loading: For deep reviews, read the relevant references/ file for the language under review.

Quick Reference

| Language | Type Safety | Linter | Complexity | |----------|-------------|--------|------------| | TypeScript | strict, no any | ESLint + typescript-eslint | max 10 | | Python | mypy strict, PEP 484 | Ruff + mypy | max 10 | | Go | staticcheck | golangci-lint | max 10 | | Rust | clippy pedantic | clippy + cargo-audit | - |

Severity Levels

| Level | Description | Action | |-------|-------------|--------| | Critical | Security vulnerabilities, data loss | Block merge | | Error | Bugs, type violations, any | Block merge | | Warning | Code smells, complexity | Must address | | Style | Formatting, naming | Auto-fix |

---

Core Rules (All Languages)

Type Safety

• No implicit any / untyped functions
• No type assertions without guards
• Explicit return types on public APIs

Security

• No hardcoded secrets (use gitleaks)
• No eval/pickle/unsafe deserialization
• Parameterized queries only
• SCA scanning (npm audit / pip-audit / govulncheck / cargo-audit)

Complexity

• Max cyclomatic complexity: 10
• Max function lines: 50
• Max nesting depth: 3
• Max parameters: 5

Error Handling

• No ignored errors (Go: no _ for err)
• No bare except (Python)
• No unwrap in prod (Rust)
• Wrap errors with context

---

Language-Specific Standards

TypeScript

See: references/typescript.md

// CRITICAL: Never use any
const bad: any = data;           // Error
const good: unknown = data;      // OK

// ERROR: No type assertions
const bad = data as User;        // Error
const good = isUser(data) ? data : null;  // OK

// ERROR: Non-null assertions
const bad = user!.name;          // Error
const good = user?.name ?? '';   // OK

Python (PEP 8 / 3.11+)

See: references/python.md

# CRITICAL: All functions must be typed
def bad(data):                   # Error
    return data

def good(data: dict[str, Any]) -> list[str]:  # OK
    return list(data.keys())

# Use modern syntax
value: str | None = None         # OK (not Optional)
items: list[str] = []            # OK (not List)

Go

See: references/go.md

// CRITICAL: Never ignore errors
result, _ := doSomething()       // Error
result, err := doSomething()     // OK
if err != nil {
    return fmt.Errorf("doing something: %w", err)
}

Rust

See: references/rust.md

// CRITICAL: No unwrap in production
let value = data.unwrap();        // Error
let value = data?;                // OK
let value = data.unwrap_or_default(); // OK

---

Cross-Language Standards

Structured Logging

See: references/logging.md

logger.info({ userId, action: 'login' }, 'User logged in');   // TS (pino)

logger.info("user_login", user_id=user_id)                    # Python (structlog)

log.Info().Str("user_id", userID).Msg("user logged in")       // Go (zerolog)

Test Coverage

See: references/testing.md

| Metric | Threshold | |--------|-----------| | Line coverage | 80% min | | Branch coverage | 70% min | | New code | 90% min |

Security Scanning

See: references/security.md

• Secrets: gitleaks (pre-commit + CI)
• Dependencies: npm audit / pip-audit / govulncheck / cargo-audit
• Accessibility: jsx-a11y (TypeScript)
• Race detection: go test -race (Go)

API Design

See: references/api-design.md

• Proper HTTP status codes (200, 201, 204, 400, 401, 403, 404, 422, 429, 500)
• RFC 7807 error format
• Plural nouns for resources: /users/{id}/orders
• Validate at API boundary

Database Patterns

See: references/database.md

• Transactions for multi-write operations
• N+1 prevention: eager load or batch
• Safe migrations (expand-contract pattern)
• Always paginate list queries

Async & Concurrency

See: references/async-concurrency.md

• Always clean up resources (try/finally, defer, Drop)
• Set timeouts on all async operations
• Use semaphores for rate limiting
• Avoid blocking in async contexts

---

Review Process

Step 1: Understand Context

1. Identify the language/framework
2. Understand the purpose of the code
3. Check for existing patterns in the codebase
4. Review any related tests

Step 2: Systematic Review

Use the checklist at references/checklist.md for thorough reviews covering:

• Code quality (structure, naming, type safety, dead code)
• Security (injection, auth, secrets, input validation)
• Performance (N+1, memory leaks, caching, re-renders)
• Error handling (edge cases, recovery, cleanup)
• Testing (coverage, quality, assertions)
• Best practices (SOLID, patterns, maintainability)

Step 3: Categorize & Report

**[SEVERITY] Issue Title**
- File: `path/to/file.ts:line`
- Problem: Clear description
- Impact: What could go wrong
- Fix: Specific code suggestion

Git Integration

# Review staged changes
git --no-pager diff --cached

# Review specific commit
git --no-pager show <commit>

# Review PR diff
gh pr diff <number>

Review Output Format

Use severity levels from the table above (Critical / Error / Warning / Style).

# Code Review Summary

## Overview
- Files reviewed: X
- Issues found: Y (X Critical, Y Error, Z Warning)
- Recommendation: [Approve / Request Changes / Needs Discussion]

## Critical Issues
[Security vulnerabilities, data loss - must fix]

## Error Issues
[Bugs, type violations - must fix]

## Warnings
[Code smells, complexity - should address]

## Style
[Formatting, naming - auto-fixable]

## Positive Observations
[Good practices found]

---

Naming Conventions

| Element | TypeScript | Python | Go | Rust | |---------|------------|--------|-----|------| | Variables | camelCase | snake_case | camelCase | snake_case | | Functions | camelCase | snake_case | camelCase | snake_case | | Constants | SCREAMING_SNAKE | SCREAMING_SNAKE | MixedCaps | SCREAMING_SNAKE | | Types | PascalCase | PascalCase | PascalCase | PascalCase | | Files | kebab-case | snake_case | lowercase | snake_case |

AI-Friendly Patterns

1. Explicit types always
2. Single responsibility per function
3. Small functions (< 30 lines ideal)
4. Max nesting depth 3
5. Guard clauses for early returns
6. Named constants, no magic values
7. Linear, predictable execution flow

Enforcement Strategy

Progressive (Ratchet-Based)

Phase 1: Errors block, Warnings tracked
Phase 2: Strict on NEW files only
Phase 3: Strict on TOUCHED files
Phase 4: Full enforcement

WIP vs Merge Mode

| Mode | Trigger | Behavior | |------|---------|----------| | WIP | Local commit | Warnings only | | Push | git push | Errors block | | PR | PR to main | Full strict |

Config Files

Available in configs/:

• typescript/ - ESLint, tsconfig, Prettier
• python/ - pyproject.toml, pre-commit
• go/ - golangci.yaml
• rust/ - clippy.toml
• .pre-commit-config.yaml
• .gitleaks.toml

Scripts

Available in scripts/:

• check_changed.sh - Monorepo-aware incremental linting
• check_all.sh - Full repository check
• check_style.py - Python full check (ruff + pycodestyle + mypy)
• check_pep8.sh - Quick PEP 8 only
• check_types.sh - Python type hints only
• fix_style.sh - Python auto-fix issues