TypeScript Type Safety Review

Purpose: Comprehensive type safety review for TypeScript code, detecting violations that compromise compile-time safety and runtime reliability.

When to use: During code review process, invoked by review plugin to validate TypeScript type safety across the codebase.

Exported for: Cross-cutting review plugin that orchestrates multi-concern reviews.

Review Checklist

When reviewing TypeScript code, systematically check for these type safety violations:

1. any Type Abuse

Check for:

• •Generic defaults using any: <T = any>
• •Function parameters typed as any: function process(data: any)
• •Return types using any: ): any {
• •Array or object types with any: any[], Record<string, any>
• •Type assertions to any: as any

Correct alternatives:

• •Use unknown with type guards instead of any
• •Use specific types or generic constraints
• •Use the avoiding-any-types skill for guidance

Severity: HIGH - Defeats TypeScript's purpose entirely

2. Unsafe Type Assertions

Check for:

• •Type assertions on external data without validation: JSON.parse(response) as T
• •Downcasting without runtime checks: value as SpecificType
• •Double assertions: value as unknown as T
• •Type assertions in parsers or API handlers

Acceptable assertions:

• •as const for literal types
• •as unknown as T only AFTER runtime validation
• •Type assertions on known internal data structures

Severity: HIGH - Bypasses type safety, causes runtime errors

3. Missing Type Guards

Check for:

• •Error handling without type checks: catch (error) { error.message }
• •Array operations without bounds checking
• •Object property access without in operator
• •Discriminated unions without exhaustive checks

Required patterns:

• •Error type guards: error instanceof Error
• •Array bounds: check length or use noUncheckedIndexedAccess
• •Object properties: 'key' in obj before access
• •Exhaustive switch with never type

Severity: MEDIUM - Leads to runtime errors in edge cases

4. Missing Runtime Validation

Check for:

• •API responses used directly without validation
• •User input processed without sanitization
• •JSON parsing without schema validation
• •External configuration loaded without checks

Required:

• •Use Zod, io-ts, or similar for runtime validation
• •Validate at system boundaries
• •Never trust external data
• •Use the using-runtime-checks skill

Severity: HIGH - Security and reliability issue

5. Deprecated JavaScript APIs

Check for:

• •substr() - use slice() instead
• •escape() - use encodeURIComponent() instead
• •unescape() - use decodeURIComponent() instead

Severity: LOW - Future compatibility issue

6. Security Violations

Check for:

• •Base64 encoding for passwords (not encryption!)
• •Direct password storage without hashing
• •Accepting third-party credentials (use OAuth instead)
• •Missing input sanitization (XSS risk)
• •Unsafe SQL query construction

Required:

• •Use bcrypt/argon2 for password hashing
• •OAuth for third-party authentication
• •Sanitize all user input
• •Use parameterized queries
• •Use the hashing-passwords skill

Severity: CRITICAL - Production security breach risk

7. Missing Generic Constraints

Check for:

• •Unconstrained generics: <T> when <T extends SomeType> is appropriate
• •Generic defaults to any
• •Missing type parameter relationships

Correct patterns:

• •Constrain to expected shape: <T extends { id: string }>
• •Use multiple type parameters with relationships: <T extends U>
• •Use the using-generics skill

Severity: MEDIUM - Reduces type safety guarantees

8. Compiler Configuration Issues

Check for:

• •strict: false in tsconfig.json
• •Missing noUncheckedIndexedAccess: true
• •skipLibCheck: false (performance issue)
• •Incorrect module resolution for Node.js projects

Required settings:

• •strict: true (enables all strict checks)
• •noUncheckedIndexedAccess: true (prevents array out-of-bounds)
• •skipLibCheck: true (improves build performance)
• •moduleResolution: "NodeNext" for Node.js projects

Severity: MEDIUM - Affects entire project safety

Review Process

1. •

   Automated Checks

   • •Run TypeScript compiler: tsc --noEmit
   • •Run ESLint with TypeScript rules
   • •Check for any usage: grep -r ": any" src/
   • •Check for type assertions: grep -r " as " src/
2. •

   Manual Review

   • •Focus on type safety at system boundaries (API handlers, parsers)
   • •Verify runtime validation exists for external data
   • •Check error handling has proper type guards
   • •Review security-sensitive code (authentication, authorization)
3. •

   Report Findings

   • •Group by severity (CRITICAL > HIGH > MEDIUM > LOW)
   • •Provide specific file location and line number
   • •Explain why it's a violation
   • •Suggest specific fix with code example

Example Violations and Fixes

Violation: any Type on API Response

async function fetchUser(id: string): Promise<any> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

Fix:

import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;

async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  const data = await response.json();
  return UserSchema.parse(data);
}

Violation: Type Assertion Without Validation

function parseConfig(json: string) {
  return JSON.parse(json) as Config;
}

Fix:

import { z } from 'zod';

const ConfigSchema = z.object({
  apiKey: z.string(),
  timeout: z.number(),
});

type Config = z.infer<typeof ConfigSchema>;

function parseConfig(json: string): Config {
  const data = JSON.parse(json);
  return ConfigSchema.parse(data);
}

Violation: Missing Error Type Guard

try {
  await riskyOperation();
} catch (error) {
  console.error(error.message);
}

Fix:

try {
  await riskyOperation();
} catch (error) {
  if (error instanceof Error) {
    console.error(error.message);
  } else {
    console.error('Unknown error:', error);
  }
}

Integration with Review Plugin

This skill is exported with review: true frontmatter, making it discoverable by the cross-cutting review plugin.

Review plugin should:

• •Invoke this skill for TypeScript files (.ts, .tsx)
• •Run automated checks first
• •Present findings grouped by severity
• •Generate actionable review comments

Cross-plugin references:

• •React plugin: References this skill for component prop type safety
• •Next.js plugin: References this skill for server action type safety
• •Node.js plugin: References this skill for API handler type safety

Stress Test Prevention

This review skill addresses all 23 violations found in the TypeScript stress test:

• •✅ Detects any abuse (5/6 agents)
• •✅ Catches type assertion misuse (4/6 agents)
• •✅ Identifies security failures (2/6 agents)
• •✅ Flags deprecated API usage (3/6 agents)
• •✅ Ensures TypeScript vs JavaScript (2/6 agents)
• •✅ Validates runtime checking presence

Target: 90% reduction in type safety violations when used during code review.