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

• Identify the language/framework

• Understand the purpose of the code

• Check for existing patterns in the codebase

• 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

• Explicit types always

• Single responsibility per function

• Small functions (< 30 lines ideal)

• Max nesting depth 3

• Guard clauses for early returns

• Named constants, no magic values

• 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