gravitas-typescript

GRAVITAS — TypeScript 扩展

使用 TypeScript 专属模式扩展基础 GRAVITAS 技能。 先加载 skills/gravitas/SKILL.md，再加载此文件。

---

TypeScript 侦察补充

添加到标准侦察清单中：

□ 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)

严格阅读 tsconfig

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

---

TypeScript 验证链

# 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 专属反模式

切勿使用 any

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

切勿使用 as 来规避类型错误

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

明确处理 undefined

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

严格空值检查

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

---

常见 TypeScript 故障模式

故障	根本原因	修复方法
Object is possibly undefined	未经保护便访问可选属性	添加 ?. 或空值检查
Type 'string' is not assignable to 'number'	传入了错误类型	检查函数签名并修复调用方
Property does not exist on type	接口不匹配	更新接口或使用正确的属性
Cannot find module	tsconfig 中未配置路径别名	在 tsconfig 的 paths 中添加配置
Argument of type X is not assignable to Y	泛型类型不匹配	检查泛型约束
严格模式下的隐式 any	缺少类型注解	添加显式类型

---

TypeScript 模式

使用参数化类型，而非 any

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

使用可辨识联合确保类型安全

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

使用类型守卫，而非类型断言

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

---

测试模式（Vitest）

测试文件位置

遵循项目惯例——检查现有测试：

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

标准测试结构

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);
  });
});

模拟

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

---

快速参考

# 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