gravitas-typescript

GRAVITAS — TypeScript Extension

Extends the base GRAVITAS skill with TypeScript-specific patterns. Load skills/gravitas/SKILL.md first, then this file.

---

TypeScript Recon Additions

Add to standard recon checklist:

□ tsconfig.json — strict mode? noUncheckedIndexedAccess? exactOptionalPropertyTypes?
□ package.json — TypeScript version, test runner (vitest vs jest)
□ eslint config — @typescript-eslint rules in effect
□ type declarations — are there .d.ts files that affect this module?
□ path aliases — does tsconfig have paths? (affects imports)

Read tsconfig strictly

cat tsconfig.json | jq '.compilerOptions | {strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, target, lib}'

---

TypeScript Verification Chain

# Full chain — always in this order
tsc --noEmit                           # catches type errors first
eslint . --max-warnings 0              # @typescript-eslint rules
vitest run --reporter=verbose          # or: jest --verbose

# With coverage
vitest run --coverage --reporter=verbose

# Type coverage (optional, requires type-coverage)
npx type-coverage --strict

---

TypeScript-Specific Anti-Patterns

Never use any

BAD:  function process(data: any) { ... }
GOOD: function process(data: ProcessInput) { ... }

Never use as to silence type errors

BAD:  const user = data as User;  // silences real type error
GOOD: if (isUser(data)) { const user = data; ... }

Handle undefined explicitly

BAD:  const name = user.name;          // may be undefined
GOOD: const name = user.name ?? 'Anonymous';

Strict null checks

BAD:  return users.find(u => u.id === id).name;  // crash if not found
GOOD: return users.find(u => u.id === id)?.name;

---

Common TypeScript Failure Modes

Failure	Root Cause	Fix
Object is possibly undefined	Optional property accessed without guard	Add ?. or null check
Type 'string' is not assignable to 'number'	Wrong type passed	Check function signature, fix caller
Property does not exist on type	Interface mismatch	Update interface or use correct property
Cannot find module	Path alias not in tsconfig	Add to paths in tsconfig
Argument of type X is not assignable to Y	Generic type mismatch	Check generic constraints
Implicit any in strict mode	Missing type annotation	Add explicit type

---

TypeScript Patterns

Parameterized types over any

function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

Discriminated unions for type safety

type Result<T> =
  | { ok: true; data: T }
  | { ok: false; error: string };

Type guards instead of casts

function isUser(obj: unknown): obj is User {
  return typeof obj === 'object' && obj !== null && 'id' in obj;
}

---

Test Patterns (Vitest)

Test file location

Follow project convention — check existing tests:

find src/ -name "*.test.ts" | head -5  # see the pattern

Standard test structure

import { describe, it, expect, vi, beforeEach } from 'vitest';

describe('[module]', () => {
  beforeEach(() => { vi.clearAllMocks(); });

  it('[behavior] when [condition]', () => {
    // Arrange
    const input = ...;
    // Act
    const result = fn(input);
    // Assert
    expect(result).toEqual(expected);
  });
});

Mocking

vi.mock('../db', () => ({
  query: vi.fn().mockResolvedValue({ rows: [] })
}));

---

Quick Reference

# Find all TypeScript errors
tsc --noEmit 2>&1 | grep "error TS"

# Find implicit any
tsc --noEmit --strict 2>&1

# Count test files
find src/ -name "*.test.ts" | wc -l

# Run single test file
vitest run src/auth/session.test.ts

# Watch mode (dev)
vitest --watch