Type Safety Audit

You are a TypeScript type safety expert. Audit the codebase for type safety holes, unsafe patterns, and missing annotations. The goal is to maximize type coverage and eliminate runtime type errors.

Step 1: Check TypeScript Configuration

cat tsconfig.json

Check these critical settings:

• "strict": true — If false, many safety checks are disabled. Flag as HIGH priority.
• "noImplicitAny": true — Prevents untyped variables
• "strictNullChecks": true — Catches null/undefined bugs
• "noUncheckedIndexedAccess": true — Array/object access returns T | undefined
• "exactOptionalPropertyTypes": true — Distinguishes undefined from missing

If strict is false or key options are missing, flag this first — it's the highest-impact change.

Step 2: Find Type Escape Hatches

# Count `any` usage
grep -rn --include="*.ts" --include="*.tsx" ": any\b" . --exclude-dir=node_modules --exclude-dir=.next | wc -l

# List every `any` usage with context
grep -rn --include="*.ts" --include="*.tsx" ": any\b" . --exclude-dir=node_modules --exclude-dir=.next

# Find `as any` type assertions
grep -rn --include="*.ts" --include="*.tsx" "as any" . --exclude-dir=node_modules --exclude-dir=.next

# Find non-null assertions
grep -rn --include="*.ts" --include="*.tsx" "\w!" . --exclude-dir=node_modules --exclude-dir=.next | grep -v "!=\|!=" | grep "!\." | head -20

# Find @ts-ignore and @ts-expect-error
grep -rn --include="*.ts" --include="*.tsx" "@ts-ignore\|@ts-expect-error\|@ts-nocheck" . --exclude-dir=node_modules --exclude-dir=.next

For each finding:

• : any — Replace with the actual type. If unknown, use unknown and narrow with type guards.
• as any — This silences the compiler. Find the real type or fix the underlying issue.
• ! (non-null assertion) — Replace with null check: if (value) { ... } or optional chaining value?.method().
• @ts-ignore — Remove and fix the underlying type error. Every ignore is a potential runtime crash.

Step 3: Check API Boundaries

Read the API route handlers and check:

# Find API route files
find . -path "*/api/*" -name "*.ts" | grep -v node_modules | grep -v .next

For each API route:

• Is the request body validated with a schema (Zod, Joi, etc.) or just cast with as?
• Are query parameters typed or treated as string | string[] | undefined?
• Are external API responses validated before use?

Bad pattern:

// UNSAFE - trusting external data
const data = await req.json() as UserInput;

Good pattern:

// SAFE - validates at runtime
const data = UserSchema.parse(await req.json());

Step 4: Check Function Return Types

# Find functions without explicit return types
grep -rn --include="*.ts" --include="*.tsx" -E "export (async )?function \w+\([^)]*\)\s*\{" . --exclude-dir=node_modules --exclude-dir=.next | head -20

# Find arrow functions without return types
grep -rn --include="*.ts" --include="*.tsx" -E "export const \w+ = (async )?\([^)]*\)\s*=>" . --exclude-dir=node_modules --exclude-dir=.next | head -20

Public/exported functions should have explicit return types. This:

• Catches accidental return type changes
• Provides better error messages
• Serves as documentation

Step 5: Check Error Handling Types

# Find catch blocks
grep -rn --include="*.ts" --include="*.tsx" -A2 "catch\s*(" . --exclude-dir=node_modules --exclude-dir=.next | head -30

Check:

• catch (error) without type narrowing — error is unknown in strict mode. Is it being narrowed with instanceof Error before accessing .message?
• catch (e: any) — Replace with catch (e: unknown) and narrow properly
• Promise .catch() callbacks — same rules apply

Step 6: Check Generic Usage

Read through the main source files and flag:

• Collections typed as Array<any> instead of Array<User>
• Record<string, any> instead of a proper interface
• Promise<any> instead of Promise<UserResponse>
• Map<string, any> or Set<any>
• Event handlers typed as (e: any) => void instead of proper event types

Step 7: Output the Report

## Type Safety Audit Report

**Project**: [name]
**TypeScript Version**: [version from package.json]
**Strict Mode**: [enabled/disabled]

---

### Configuration Issues

1. **tsconfig.json** — [What's missing or misconfigured]
   **Fix**: [Exact config change]

### Critical Type Safety Holes

1. **[file:line]** — [Issue]
   **Risk**: [What could go wrong at runtime]
   **Fix**:
   ```suggestion
   // Show the type-safe version

Type Escape Hatches to Remove

File	Line	Pattern	Suggested Fix
...	...	any	UserInput

Missing Validations

1. [file:line] — [Where external data is trusted without validation] Fix: [Add Zod schema / type guard]

Statistics

Metric	Count
any usage	...
as any assertions	...
! non-null assertions	...
@ts-ignore comments	...
Untyped function returns	...
Unvalidated API inputs	...

Summary

Type Safety Score: [LOW / MEDIUM / HIGH]

Top 3 improvements:

1. [Highest impact change]
2. [Second]
3. [Third]

## Rules

- Every `any` should have a specific replacement type suggested.
- Don't just count problems — for critical ones, show the fixed code.
- Distinguish between intentional `any` (rare, should have a comment explaining why) and lazy `any` (should be fixed).
- API boundaries (incoming requests, external API responses, user input) are the highest priority — type errors here cause production crashes.
- Don't flag generated code (e.g., Prisma client, GraphQL codegen output).

## Common Pitfalls

- Treating this skill as a one-shot solution — most workflows need iteration and verification
- Skipping the verification steps — you don't know it worked until you measure
- Applying this skill without understanding the underlying problem — read the related docs first


## When NOT to Use This Skill

- When a simpler manual approach would take less than 10 minutes
- On critical production systems without testing in staging first
- When you don't have permission or authorization to make these changes


## How to Verify It Worked

- Run the verification steps documented above
- Compare the output against your expected baseline
- Check logs for any warnings or errors — silent failures are the worst kind


## Production Considerations

- Test in staging before deploying to production
- Have a rollback plan — every change should be reversible
- Monitor the affected systems for at least 24 hours after the change