gravitas-typescript

GRAVITAS — TypeScript 拡張

ベースとなる GRAVITAS スキルを、TypeScript 固有のパターンで拡張します。 まず 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';

厳密な null チェック

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	ガードなしでオプショナルプロパティにアクセスしている	?. または null チェックを追加する
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	ジェネリック型が一致していない	ジェネリック制約を確認する
strict モードでの暗黙的な 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