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