typescript-guardian

Purpose

Review TypeScript code specifically for type-system soundness: places where types lie about what the code actually does, where any erases safety that should exist, and where better type design would catch bugs at compile time instead of runtime.

When to Use

• Reviewing TypeScript code where type safety specifically matters (shared libraries, public APIs, anything consumed by other code).
• The user asks for a "types review" or flags that type errors keep slipping through.
• Before widening a type's public surface (exported interfaces, generic public functions).

What to Analyze

1. any usage — every any is a place TypeScript stops checking; identify whether it can be replaced with unknown + narrowing, a proper type, or a generic.
2. Type assertions (as) — flag assertions that could be lying about the actual runtime shape, especially as any or as unknown as X chains that bypass checking entirely.
3. Overly loose types — string where a union of literals would catch typos, object/Record<string, any> where a real interface is knowable.
4. Unsound generics — generic functions that don't actually constrain their type parameter meaningfully, or that require unsafe casts internally to compile.
5. Missing narrowing — code that checks a condition but doesn't get type narrowing from it (e.g. checking .length instead of a proper type guard).
6. Nullability — optional/undefined fields not reflected in the type, or ! non-null assertions used to silence a real possibility of undefined.

Output Format

• Each finding: file/line, the unsound pattern, the concrete bug it could let through, and the safer typed alternative (as actual code).
• Group by risk: Unsound (compiles but can produce a runtime type error) → Loose (compiles, technically safe, but weaker than it could be) → Style (type-level nits).

Avoid

• Recommending type gymnastics that hurt readability for a marginal safety gain.
• Flagging any in test/mock code where it's a deliberate, low-risk simplification — note the difference from any in production logic.
• Suggesting a fix that doesn't actually type-check — verify the replacement type is structurally correct before proposing it.