typescript.yaml

# TypeScript Code Review Guidelines
# Comprehensive rules for TypeScript code quality, type safety, and best practices

name: TypeScript Code Review Guidelines
description: Guidelines for reviewing TypeScript code covering type safety, security, performance, and best practices
globs:
  - "**/*.ts"
  - "**/*.tsx"

areas:
  - name: type_safety
    description: Rules for maintaining strong type safety
    rules:
      - name: avoid-any-type
        description: Avoid using 'any' type as it disables type checking. Use 'unknown' for truly unknown types and narrow with type guards. If any is unavoidable, add a comment explaining why and consider using a more specific type.
        severity: high
        
      - name: proper-null-checks
        description: Always handle null and undefined explicitly. Enable strictNullChecks in tsconfig. Use optional chaining (?.) and nullish coalescing (??) operators. Never use non-null assertion (!) without absolute certainty.
        severity: high
        
      - name: enable-strict-mode
        description: Enable strict mode in tsconfig.json. This includes strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitAny, noImplicitThis, and alwaysStrict.
        severity: high
        
      - name: avoid-type-assertions
        description: Minimize use of type assertions (as Type). They bypass type checking and can hide bugs. Prefer type guards, type narrowing, or refactoring. If needed, use unknown as intermediate step.
        severity: medium
        
      - name: use-const-assertions
        description: Use const assertions (as const) for literal types and readonly arrays/objects. This prevents accidental mutation and enables more precise type inference for constant values.
        severity: low
        
      - name: proper-generic-constraints
        description: Use generic constraints (extends) to ensure type parameters have required properties. Prefer unknown over any as the default constraint. Use conditional types for complex type logic.
        severity: medium
        
      - name: exhaustive-switch-checks
        description: Use exhaustive type checking in switch statements with never type. This ensures all cases are handled and will cause compile errors when new union members are added.
        severity: medium

  - name: security
    description: Security-related rules for TypeScript/JavaScript
    rules:
      - name: prevent-xss
        description: Never use innerHTML, outerHTML, or document.write with user input. Use textContent for plain text, or sanitize HTML with DOMPurify. In React, avoid dangerouslySetInnerHTML.
        severity: high
        
      - name: prevent-prototype-pollution
        description: Validate object keys before using bracket notation with user input. Use Object.hasOwn() instead of hasOwnProperty. Consider using Map for user-provided keys. Freeze prototypes if necessary.
        severity: high
        
      - name: avoid-unsafe-type-coercion
        description: Be explicit about type conversions. Avoid relying on implicit coercion. Use Number(), String(), Boolean() explicitly. Never use == for comparisons, always use ===.
        severity: medium
        
      - name: validate-external-data
        description: Always validate data from external sources (APIs, user input, localStorage). Use runtime validation with Zod, io-ts, or similar. Never trust type assertions for external data.
        severity: high
        
      - name: secure-regex-patterns
        description: Avoid regex patterns vulnerable to ReDoS (catastrophic backtracking). Limit input length, use atomic groups when available, and consider using safe-regex to validate patterns.
        severity: medium
        
      - name: sanitize-urls
        description: Validate and sanitize URLs before use. Check for javascript colon protocol, data URIs, and other potentially dangerous schemes. Use URL constructor for parsing and validation.
        severity: high

  - name: performance
    description: Performance optimization rules
    rules:
      - name: optimize-bundle-size
        description: Use named imports instead of default imports for tree-shakeable libraries. Avoid importing entire libraries when only specific functions are needed. Use dynamic imports for code splitting.
        severity: medium
        
      - name: proper-imports
        description: Use path aliases to avoid deep relative imports. Organize imports consistently. Remove unused imports. Consider using import type for type-only imports to reduce bundle size.
        severity: low
        
      - name: avoid-memory-leaks
        description: Clean up event listeners, subscriptions, and timers in cleanup functions. Use WeakMap/WeakSet for object references that shouldn't prevent garbage collection. Watch for closure leaks.
        severity: high
        
      - name: memoize-expensive-computations
        description: Use useMemo, useCallback in React, or memoization libraries for expensive computations. Cache results of pure functions. Be mindful of referential equality in dependency arrays.
        severity: medium
        
      - name: lazy-load-modules
        description: Use dynamic imports for large modules that aren't needed immediately. Implement code splitting at route level. Consider using React.lazy and Suspense for component lazy loading.
        severity: medium

  - name: best_practices
    description: TypeScript best practices and idioms
    rules:
      - name: interface-vs-type
        description: Use interfaces for object shapes that might be extended. Use type aliases for unions, intersections, mapped types, and conditional types. Be consistent within the codebase.
        severity: low
        
      - name: avoid-enums
        description: Prefer const objects with as const or union types over enums. Enums have runtime overhead and can have surprising behavior. Use string literal unions for simple cases.
        severity: low
        
      - name: use-readonly
        description: Use readonly modifier for properties that shouldn't change. Use ReadonlyArray, Readonly utility type, and Object.freeze() for immutable data structures.
        severity: medium
        
      - name: proper-error-handling
        description: Create custom error classes extending Error. Use discriminated unions for result types. Never throw non-Error objects. Consider using Result or Either patterns for recoverable errors.
        severity: medium

      - name: use-utility-types
        description: Leverage TypeScript utility types (Partial, Required, Pick, Omit, Record, etc.) instead of manually defining similar types. They're well-tested and widely understood.
        severity: low

      - name: avoid-namespace
        description: Avoid using namespace and module keywords. Use ES modules instead. Namespaces are legacy and can cause issues with tree shaking and module bundlers.
        severity: medium

      - name: discriminated-unions
        description: Use discriminated unions with a literal type discriminator for type-safe state management. This enables exhaustive pattern matching and better type narrowing.
        severity: medium

      - name: proper-async-types
        description: Always type Promise return values explicitly. Use Promise as return type for async functions. Don't forget to handle rejected promises with proper error types.
        severity: medium

      - name: avoid-object-type
        description: Avoid using Object, object, or {} as types. Use Record for key-value pairs, unknown for truly unknown types, or define specific interfaces for expected shapes.
        severity: medium

      - name: use-branded-types
        description: Consider branded types for type-safe IDs and domain-specific values. This prevents accidentally mixing different ID types (UserId vs OrderId) that are structurally identical.
        severity: low