throw-trace

TypeScriptの@throws TSDoc宣言の漏れを検出する静的解析ツール。

関数が投げる可能性のある例外を追跡し、@throwsが正しく宣言されているかをチェックします。

インストール

# npm
npx throw-trace --help

# cargo
cargo install throw-trace

使い方

基本

# カレントディレクトリをチェック
throw-trace check

# 特定のファイルやディレクトリを指定
throw-trace check src/
throw-trace check src/service.ts

オプション

# 除外パターンを指定
throw-trace check src/ --exclude "**/*.test.ts"

# JSON形式で出力
throw-trace check src/ --format json

同期（fix）

解析したthrow契約に合わせて、@throws宣言を同期します。 不足する宣言を追加し、型だけ、またはfrom句付きの機械管理可能な宣言がstaleなら削除します。 説明文付きの手書き宣言は、解析対象外のthrow情報を失わないよう保持します。

# カレントディレクトリを修正
throw-trace fix

# 特定のファイルやディレクトリを指定
throw-trace fix src/

# 除外パターンを指定
throw-trace fix src/ --exclude "**/*.test.ts"

挿入される宣言には伝播元の情報が含まれます：

/**
 * @throws {ValidationError} from validator.ts:validate
 */
function createUser(name: string) {
  validate(name);
}

Exit code

code	意味
0	違反なし
1	@throws宣言の漏れを検出
2	実行時エラー（存在しないパス、不正なオプションなど）

検出例

以下のコードでは、createUser関数がvalidateを呼び出していますが、@throwsが宣言されていません。

/**
 * @throws {ValidationError} 入力が不正な場合
 */
function validate(input: string) {
  if (!input) {
    throw new ValidationError("Input required");
  }
}

// @throws宣言が漏れている
function createUser(name: string) {
  validate(name);  // ValidationErrorが伝播する可能性
  // ...
}

throw-traceはこれを検出し、以下のように報告します：

error: missing @throws declaration
  --> src/service.ts:createUser
   |
   | ValidationError propagates from src/validator.ts
   |
   = help: add @throws {ValidationError} to function createUser

対応パターン

throw検出

throw new ValidationError("msg");     // Named型として検出
throw new Error("msg");               // Named型として検出
throw "error";                        // Unknown型

Unknown型の扱い

throw式から型名を静的に特定できない場合、その throw は Unknown として扱われます。 tsserverが利用可能なら throw 元のソース位置で型解決を試み、解決できた型名（例: Error）で照合します。

型解決できなかった Unknown は、@throws {unknown} で宣言すると満たせます：

/**
 * @throws {unknown}
 */
function rethrow(e: unknown) {
  throw e;
}

throw-trace fix が生成する @throws {unknown} from <file>:<func> の from 句は伝播元を示す補足情報で、照合には型名のみが使われます（from 句なしでも満たせます）。

try-catch捕捉

function safe() {
  try {
    riskyOperation();
  } catch (e) {
    if (e instanceof ValidationError) {
      return null;  // ValidationErrorは捕捉済み → @throws不要
    }
    throw e;        // その他はre-throw → @throws必要
  }
}

伝播追跡

呼び出し先の関数が投げる例外は、呼び出し元にも伝播します。throw-traceはcall graphを構築し、再帰的に追跡します。

出力形式

text（デフォルト）

error: missing @throws declaration
  --> src/service.ts:createUser
   |
   | ValidationError propagates from Span { start: 50, end: 80 }
   |
   = help: add @throws {ValidationError} to function createUser

Found 3 errors in 2 files

json

{
  "diagnostics": [
    {
      "file": "src/service.ts",
      "function": "createUser",
      "missing_throws": [
        {
          "error_type": "ValidationError",
          "origin_file": "",
          "origin_line": 50
        }
      ]
    }
  ],
  "summary": {
    "errors": 3,
    "files_checked": 10
  }
}

外部ライブラリについて

外部ライブラリ（npm packages、Node.js標準ライブラリ）の関数呼び出しは追跡対象外です。外部ライブラリを呼び出す境界となる関数には、手動で@throwsを記述してください。

ライセンス

MIT License - see LICENSE for details