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:

Copy code
□ 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

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

TypeScript Verification Chain

bashCopy code
# 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

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

Never use as to silence type errors

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

Handle undefined explicitly

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

Strict null checks

typescriptCopy code
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

TypeScript Patterns

Parameterized types over any

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

Discriminated unions for type safety

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

Type guards instead of casts

typescriptCopy code
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:

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

Standard test structure

typescriptCopy code
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

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

Quick Reference

bashCopy code
# 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