typegap

typegap

每个代码库中都有一些类型系统已经放弃的文件：这里有一处强制转换为 any，那里有一处 @ts-ignore。typegap 会告诉你哪些文件造成的影响最大。它会统计每个文件的类型债务，并根据有多少其他文件导入该文件来加权评分，因此，半个代码库都依赖的潦草文件，排名会高于同样潦草但无人触碰的叶子文件。

• any 计数——六类文本模式，按固定顺序逐行匹配；每类匹配的片段都会在运行下一类之前移除，因此不会重复计数：

  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> 计数；: any[] 则只在 any[] 类别中计一次。

• 抑制计数——对整个文件进行纯子字符串计数：@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、路径为空或不是字符串或重复、content 不是字符串，或 imported_by 不是大于等于 0 的整数，都会报错并指出有问题的路径（例如 files[1].imported_by must be an integer >= 0），且不会生成部分排名。计算纯粹在本地进行：不访问网络、不需要配置，也不会读取你传入输入之外的文件。

命令行界面

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（数组，必填，至少一个）——源文件，格式为 {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 — 版权所有 (c) 2026 Rene Turcios