Typescript Type Auditor

The Problem

Your tsconfig.json has strict: true and noImplicitAny: true. Your CI passes. Your tests pass. Then a user hits Cannot read properties of undefined (reading 'toUpperCase') in production. You enabled strict mode but that only catches the easy stuff — implicit any in function params. It doesn't catch the as ApiResponse assertion on a fetch() response that might return HTML. It doesn't catch the @ts-ignore that someone added six months ago to suppress a real error. It doesn't catch the discriminated union with a switch statement that's missing two cases.

Your type safety score might look like 90/100 because the compiler is happy. But compiler-passing TypeScript and safe TypeScript are not the same thing.

What You Get

• Seven-category type safety audit — Implicit Any (parameters, return types, variables), Unsafe Casts (as Type assertions), Null Safety (missing guards on possibly-null values), Type Narrowing (incomplete exhaustiveness checks), Generics (unconstrained parameters, missing type arguments), Index Signatures (unsafe dynamic property access), Type Overrides (@ts-ignore, @ts-expect-error without explanation)
• tsconfig-aware analysis — reads your tsconfig.json strict flags and skips checks already enforced by the compiler, so you only see gaps the compiler misses
• Severity classification by runtime risk — Critical = likely runtime error (unsafe assertions, suppressed errors), High = probable runtime error (implicit any on external data), Medium = silent failure risk (incomplete narrowing), Low = style concern (redundant annotations)
• Type Safety Score — quantitative metric (0-100) tracking your codebase's type safety maturity, usable as a sprint-over-sprint trend
• Fix suggestions with code patterns — each finding includes the exact code change, not just "add a type annotation" but which type, where to put it, and what library to use for runtime validation

Why This Beats Prompting It Yourself

Running tsc --noImplicitAny only catches the category with its name. This audit catches the other six categories that strict mode silently allows: as Type assertions that bypass the compiler entirely, @ts-ignore directives that suppress real errors, discriminated union switch statements that silently fall through, and null access on optional properties that the type system promises exist but may not. Each finding carries a runtime risk assessment based on whether the code path handles external data (API responses, user input, database results).

Example Session

You: "Audit this project's type safety. It's a Next.js API with 47 TypeScript files."

Agent:

# TypeScript Type Safety Audit Report
Project: my-api | Files Scanned: 47 | Issues Found: 23

Severity  Count  Description
────────  ─────  ────────────────────────────────────────────
Critical  4      Unsafe type assertions and suppressed errors
High      8      Implicit any and missing null checks
Medium    7      Incomplete type narrowing and unconstrained
                 generics
Low       4      Style-level type annotations

CRITICAL ISSUES
═══════════════
1. Unsafe type assertion bypasses compiler check
- File: src/api/client.ts:42
- Code: const response = await fetch(url) as ApiResponse;
- Risk: fetch() can return non-JSON; assertion masks runtime errors
- Fix: const data = ApiResponseSchema.parse(await res.json())

2. @ts-ignore suppresses type error without comment
- File: src/utils/helpers.ts:15
- Code: // @ts-ignore → return obj.unknownProp
- Risk: Silently ignores error; breaks if property renamed
- Fix: Add @ts-expect-

Use Cases

• Pre-merge gate — run before merging feature branches to catch type safety regressions that strict mode misses
• JS-to-TS migration validation — audit a migration for remaining unsafe patterns and residual any usage
• CI/CD enforcement — add to pipeline to prevent accumulation of @ts-ignore directives and track type safety score over time
• Library publishing — verify public API types are safe and properly annotated before releasing to npm
• Tech debt quantification — use the Type Safety Score as a sprint planning metric for refactoring prioritization

Known Limitations

The auditor uses regex-based detection patterns rather than full AST parsing, so complex type expressions may produce occasional false positives on critical findings. Cross-file type inference is limited — type definitions in separate files are not correlated. The tool works on .ts and .tsx source files only; compiled output, d.ts files, and JavaScript with JSDoc types are partially supported.