typegap

typegap

どのコードベースにも、型チェックを諦めたファイルがあります。ここに any へのキャスト、あちらに @ts-ignore。typegap は、その中でも特に問題の大きいファイルを教えてくれます。ファイルごとの型負債を数え、各ファイルのスコアに、そのファイルをインポートしている他のファイル数を加味します。そのため、コードベースの半分が依存するずさんなファイルは、同じくらいずさんでも誰も触れない末端のファイルより上位にランクされます。

• any の数 — 6 種類のテキストパターンを決められた順序で1行ずつ適用します。各パターンで一致した範囲は次のパターンを実行する前に取り除くため、同じ範囲が二重に数えられることはありません。

  1. Array<any>（Array の前には境界、つまり [A-Za-z0-9_$] 以外の文字または行の端が必要です）
  2. Record<string, any> と Record<string,any>（Record の前には境界が必要です）
  3. <any>（境界の要件はありません）
  4. any[]（any の前には境界が必要です。そのため、company[] は数えられません）
  5. : any（any の後の文字は境界である必要があります）
  6. as any（as の前と any の後には境界が必要です。そのため、has any は数えられません）

  先に実行したパターンで一致範囲を取り除くため、Array<any> は <any> として再度数えられず、1回だけ数えられます。また、: any[] は any[] として1回だけ数えられます。

• 抑制カウント — ファイル全体を対象に、単純な部分文字列の数を数えます。対象は @ts-ignore、@ts-expect-error、@ts-nocheck です。

• 負債と影響範囲 — debt = 2 * any_count + 3 * ts_ignore_count + 1 * ts_expect_error_count + 5 * ts_nocheck_count、blast_radius = debt * (1 + imported_by) です。コンパイラーを黙らせる抑制は、単独の any より重く評価されます。ファイル全体を型チェックの対象外にする @ts-nocheck は、最も重く評価されます。

カウントは意図的にテキストベースです。コメントや文字列リテラルは解析しないため、その中にあるパターンもコードと同様に数えられます。これによりツールの動作は決定的になり、対象範囲も明確です。測定するのは負債マーカーが集中している場所であり、コンパイラーがそれらをどう解釈するかではありません。

結果には負債のあるファイルだけが表示され、影響範囲の降順、次に負債の降順、最後にパスの昇順で並びます。ファイル一覧とともに、スキャンしたファイル数、負債のあるファイル数、指定されたすべてのファイルの any と負債の合計、最も問題の大きいファイルのパス（負債のあるファイルがない場合は null）も報告されます。

検証は厳密です。ファイル一覧が存在しない、または空の場合、ファイルに path または content がない場合、path が空、文字列以外、または重複している場合、content が文字列以外の場合、あるいは imported_by が >= 0 の整数でない場合は、該当するパスを示すエラーになります（例：files[1].imported_by must be an integer >= 0）。部分的なランキングは生成されません。計算は純粋かつローカルで行われます。ネットワークや設定は不要で、渡された入力以外のファイルを読み込むこともありません。

CLI

npx @reneturcios/typegap rank --input args.json
npx @reneturcios/typegap --version

args.json には引数オブジェクト全体が含まれます。

{
  "files": [
    {
      "path": "src/api.ts",
      "content": "let raw: any;\n// @ts-ignore\n",
      "imported_by": 12
    },
    { "path": "src/clean.ts", "content": "export const n: number = 1;\n" }
  ]
}

imported_by はファイルごとに省略可能で、省略時は 0 になります。content は必須ですが、空でもかまいません。ランキングは JSON として出力されます。

{
  "files": [
    {
      "path": "src/api.ts",
      "any_count": 1,
      "ts_ignore_count": 1,
      "ts_expect_error_count": 0,
      "ts_nocheck_count": 0,
      "debt": 5,
      "imported_by": 12,
      "blast_radius": 65
    }
  ],
  "scanned_files": 2,
  "files_with_debt": 1,
  "total_any": 1,
  "total_debt": 5,
  "worst_file": "src/api.ts"
}

終了コード：成功時は 0、実行時エラー時（読み取れない、または無効な入力ファイル、無効な入力を含む）は 1、使用方法のエラー時は 2 です。

MCP サーバー

npx -y @reneturcios/typegap mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "typegap": {
      "command": "npx",
      "args": ["-y", "@reneturcios/typegap", "mcp"]
    }
  }
}

ツール

• rank_type_debt — ファイルを型負債の順にランク付けします。

  • files（配列、必須、1件以上）— {path, content, imported_by?} オブジェクト形式のソースファイル。path はセット内で一意である必要があります。content はソーステキスト全体、imported_by はそのファイルをインポートしている他のファイル数を表します。

  {files, scanned_files, files_with_debt, total_any, total_debt, worst_file} を返します。

Docker

docker run -i ghcr.io/cloudcorprecords/typegap
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/typegap rank --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios